CMake¶

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 (from the generator CMakeToolchain) 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()

Reference¶

class CMake(conanfile)¶

CMake helper to use together with the CMakeToolchain feature

Parameters:: conanfile – The current recipe object. Always use self.

configure(variables=None, build_script_folder=None, cli_args=None, stdout=None, stderr=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.

and call cmake.

Parameters:

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_script_folder – Path to the CMakeLists.txt in case it is not in the declared self.folders.source at the layout() method.
cli_args – List of arguments [arg1, arg2, ...] that will be passed as extra CLI arguments to pass to cmake invocation
stdout – Use it to redirect stdout to this stream
stderr – Use it to redirect stderr to this stream

build(build_type=None, target=None, cli_args=None, build_tool_args=None, stdout=None, stderr=None)¶

Parameters:

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 – The name of a single build target as a string, or names of multiple build targets in a list of strings to be passed to the --target argument.
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
stdout – Use it to redirect stdout to this stream
stderr – Use it to redirect stderr to this stream

install(build_type=None, component=None, cli_args=None, stdout=None, stderr=None)¶

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

Parameters:

component – The specific component to install, if any
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.
cli_args – A list of arguments [arg1, arg2, ...] for the underlying build system that will be passed to the command line: cmake --install ... arg1 arg2
stdout – Use it to redirect stdout to this stream
stderr – Use it to redirect stderr to this stream

test(build_type=None, target=None, cli_args=None, build_tool_args=None, env='', stdout=None, stderr=None)¶

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

Parameters:

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 time.
target – Name of the build target to run, by default RUN_TESTS or test
cli_args – Same as above build(), a list of arguments [arg1, arg2, ...] to be passed as extra arguments for the underlying build system
build_tool_args – Same as above build()
stdout – Use it to redirect stdout to this stream
stderr – Use it to redirect stderr to this stream

ctest(cli_args=None, env='', stdout=None, stderr=None)¶

Equivalent to running ctest …

Parameters:

cli_args – List of arguments [arg1, arg2, ...] to be passed as extra ctest command line arguments
env – the environment files to activate, by default conanbuild + conanrun
stdout – Use it to redirect stdout to this stream
stderr – Use it to redirect stderr to this stream

conf¶

The CMake() build helper is affected by these [conf] variables:

tools.build:verbosity will accept one of quiet or verbose 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.compilation:verbosity will accept one of quiet or verbose to be passed to CMake, which sets -DCMAKE_VERBOSE_MAKEFILE if verbose
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. If max_cpu_count=0, then it will use /m without arguments, which means use all available cpus.
tools.cmake:cmake_program specify the location of the CMake executable, instead of using the one found in the PATH.
tools.cmake:install_strip will pass --strip to the cmake --install call if set to True.