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()
Experimental feature. CMake.configure()
, CMake.build()
and CMake.install()
methods have the subfolder parameter in case you have
more than one CMakeLists.txt
in different folders.
This feature allows you to call the configure build and install method of each CMakeLists.txt
separately and without mixing the generated files and artifacts, also creating these folders in the
build folder and package folder.
In the following example, we can see what it would look like if we had two different CMakeLists.txt (cmake_1/CMakeLists.txt and cmake_2/CMakeLists.txt) in the folder1 and folder2 folders.
def build(self):
cmake = CMake(self)
# Configure and build source_folder/cmake_1/CMakeLists.txt in folder1
cmake.configure(build_script_folder="cmake_1", subfolder="folder1")
cmake.build(subfolder="folder1")
# Configure and build source_folder/cmake_2/CMakeLists.txt in folder2
cmake.configure(build_script_folder="cmake_2" subfolder="folder2")
cmake.build(subfolder="folder2")
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, subfolder=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 inCMakeToolchain
to be provided in theconan_toolchain.cmake
file. Thisvariables
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 thelayout()
method.cli_args – List of arguments
[arg1, arg2, ...]
that will be passed as extra CLI arguments to pass to cmake invocationsubfolder – (Experimental): The name of a subfolder to be created inside the
build_folder
and thepackage_folder
. If not provided, files will be placed in thebuild_folder
and thepackage_folder
root.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, subfolder=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 thecmake --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
subfolder – (Experimental): The name of a subfolder to be created inside the
build_folder
and thepackage_folder
. If not provided, files will be placed in thebuild_folder
and thepackage_folder
root.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, subfolder=None)¶
Equivalent to running
cmake --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
subfolder – (Experimental): The name of a subfolder to be created inside the
build_folder
and thepackage_folder
. If not provided, files will be placed in thebuild_folder
and thepackage_folder
root.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
ortest
cli_args – Same as above
build()
, a list of arguments[arg1, arg2, ...]
to be passed as extra arguments for the underlying build systembuild_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 argumentsenv – 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 ofquiet
orverbose
to be passed to theCMake.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 callcmake --build . --config Release -- /verbosity:Diagnostic
tools.compilation:verbosity
will accept one ofquiet
orverbose
to be passed to CMake, which sets-DCMAKE_VERBOSE_MAKEFILE
ifverbose
tools.build:jobs
argument for the--jobs
parameter when running Ninja generator.tools.microsoft.msbuild:max_cpu_count
argument for the/m
(/maxCpuCount
) when runningMSBuild
. Ifmax_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 thePATH
.tools.cmake:install_strip
(deprecated usetools.build:install_strip
) will pass--strip
to thecmake --install
call if set toTrue
.tools.build:install_strip
(Since Conan 2.18.0) will pass--strip
to thecmake --install
call if set toTrue
.