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.