CMake

Warning

These tools are experimental and subject to breaking changes.

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=conan_toolchain.cmake to the configure() call.

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 conans 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, parallel=True, namespace=None):

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

  • parallel: (Optional, Defaulted to True): If True, will append the -jN attribute (/m: in MSBuild) for parallel building being N the value of the tools.microsoft.msbuild:max_cpu_count.

  • namespace: this argument avoids collisions when you have multiple toolchain calls in the same recipe. By setting this argument the conanbuild.conf file used to pass some information to the toolchain will be named as: <namespace>_conanbuild.conf. The default value is None meaning that the name of the generated file is conanbuild.conf. This namespace must be also set with the same value in the constructor of the CMakeToolchain so that it reads the information from the proper file.

configure()

def configure(self, build_script_folder=None):

Calls cmake, with the generator defined in the cmake_generator field of the conanbuild.conf file, and passing -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake.

Important

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

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

build()

def build(self, build_type=None, target=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.

install()

def install(self, build_type=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.

test()

def test(self, build_type=None, target=None, output_on_failure=False):

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.

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.ninja:jobs argument for the --jobs parameter when running Ninja generator. (overrides the general tools.build:processes).

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