CMake

Important

Some of the features used in this section are still under development, while they are recommended and usable and we will try not to break them in future releases, some breaking changes might still happen if necessary to prepare for the Conan 2.0 release.

Available since: 1.32.0

The CMake build helper is a wrapper around the command line invocation of cmake. It will abstract the calls like cmake --build . --config Release into Python method calls. It will also add the argument -DCMAKE_TOOLCHAIN_FILE=<path>/conan_toolchain.cmake to the configure() call, as well as other possible arguments like -DCMAKE_BUILD_TYPE=<config>. The arguments that will be used are obtained from a generated CMakePresets.json file.

The helper is intended to be used in the build() method, to call CMake commands automatically when a package is being built directly by Conan (create, install)

from conan import ConanFile
from conan.tools.cmake import CMake, CMakeToolchain, CMakeDeps

class App(ConanFile):
    settings = "os", "arch", "compiler", "build_type"
    requires = "hello/0.1"
    options = {"shared": [True, False], "fPIC": [True, False]}
    default_options = {"shared": False, "fPIC": True}

    def generate(self):
        tc = CMakeToolchain(self)
        tc.generate()
        deps = CMakeDeps(self)
        deps.generate()

    def build(self):
        cmake = CMake(self)
        cmake.configure()
        cmake.build()

Note: This helper includes the additional flag -DCMAKE_SH=”CMAKE_SH-NOTFOUND” when using the MinGW Makefiles CMake’s generator, to avoid the error of sh being in the PATH (CMake version < 3.17.0).

It supports the following methods:

constructor

def __init__(self, conanfile):

  • conanfile: the current recipe object. Always use self.

configure()

def configure(self, variables=None, build_script_folder=None, cli_args=None):

Reads the CMakePresets.json file generated by the CMakeToolchain to get:

  • The generator, to append -G="xxx".

  • The path to the toolchain and append -DCMAKE_TOOLCHAIN_FILE=<path>/conan_toolchain.cmake

  • The declared cache variables and append -Dxxx.

  • build_script_folder: Relative path to the folder containing the root CMakeLists.txt

  • cli_args: List of extra arguments provided when calling to CMake.

and call cmake.

Important

If CMakePresets.json file is not there, Conan will raise an exception because it’s a mandatory one even though it’s empty.

  • variables: should be a dictionary of CMake variables and values, that will be mapped to command line -DVAR=VALUE arguments. Recall that in the general case information to CMake should be passed in CMakeToolchain to be provided in the conan_toolchain.cmake file. This variables argument is intended for exceptional cases that wouldn’t work in the toolchain approach.

build()

def build(self, build_type=None, target=None, cli_args=None, build_tool_args=None):

Calls the build system. Equivalent to cmake --build . in the build folder.

  • build_type: Use it only to override the value defined in the settings.build_type for a multi-configuration generator (e.g. Visual Studio, XCode). This value will be ignored for single-configuration generators, they will use the one defined in the toolchain file during the install step.

  • target: name of the build target to run.

  • cli_args: A list of arguments [arg1, arg2, ...] that will be passed to the cmake --build ... arg1 arg2 command directly.

  • build_tool_args: A list of arguments [barg1, barg2, ...] for the underlying build system that will be passed to the command line after the -- indicator: cmake --build ... -- barg1 barg2

install()

def install(self, build_type=None, component=None):

Equivalent to run cmake --build . --target=install

  • build_type: Use it only to override the value defined in the settings.build_type. It can fail if the build is single configuration (e.g. Unix Makefiles), as in that case the build type must be specified at configure time, not build type.

  • component: Passes the --component=<component> argument to the CMake install command.

test()

def test(self, build_type=None, target=None, cli_args=None, build_tool_args=None):

Equivalent to running cmake --build . --target=RUN_TESTS.

  • build_type: Use it only to override the value defined in the settings.build_type. It can fail if the build is single configuration (e.g. Unix Makefiles), as in that case the build type must be specified at configure time, not build type.

  • target: name of the build target to run, by default RUN_TESTS or test.

  • cli_args: Same as above build()

  • build_tool_args: Same as above build()

conf

  • tools.microsoft.msbuild:verbosity will accept one of "Quiet", "Minimal", "Normal", "Detailed", "Diagnostic" to be passed to the CMake.build() command, when a Visual Studio generator (MSBuild build system) is being used for CMake. It is passed as an argument to the underlying build system via the call cmake --build . --config Release -- /verbosity:Diagnostic

  • tools.build:jobs argument for the --jobs parameter when running Ninja generator.

  • tools.microsoft.msbuild:max_cpu_count argument for the /m (/maxCpuCount) when running MSBuild

  • tools.cmake:install_strip is a boolean parameter used to specify whether the --strip option should be enabled or disabled during the execution of the cmake --install command. (Defaulted to False)