CMake
The CMake class helps us to invoke cmake command with the generator, flags and definitions, reflecting the specified Conan settings.
There are two ways to invoke your cmake tools:
Using the helper attributes
cmake.command_line
andcmake.build_config
:
from conans import ConanFile, CMake
class ExampleConan(ConanFile):
...
def build(self):
cmake = CMake(self)
self.run('cmake "%s" %s' % (self.source_folder, cmake.command_line))
self.run('cmake --build . %s' % cmake.build_config)
self.run('cmake --build . --target install')
Using the helper methods:
from conans import ConanFile, CMake
class ExampleConan(ConanFile):
...
def build(self):
cmake = CMake(self)
# same as cmake.configure(source_folder=self.source_folder, build_folder=self.build_folder)
cmake.configure()
cmake.build()
cmake.test() # Build the "RUN_TESTS" or "test" target
# Build the "install" target, defining CMAKE_INSTALL_PREFIX to self.package_folder
cmake.install()
Constructor
class CMake(object):
def __init__(self, conanfile, generator=None, cmake_system_name=True,
parallel=True, build_type=None, toolset=None, make_program=None,
set_cmake_flags=False, msbuild_verbosity='minimal', cmake_program=None,
generator_platform=None, append_vcvars=False)
- Parameters:
conanfile (Required): Conanfile object. Usually
self
in a conanfile.pygenerator (Optional, Defaulted to
None
): Specify a custom generator instead of autodetect it. e.g., “MinGW Makefiles”cmake_system_name (Optional, Defaulted to
True
): Specify a custom value forCMAKE_SYSTEM_NAME
instead of autodetect it.parallel (Optional, Defaulted to
True
): IfTrue
, will append the -jN attribute for parallel building being N the cpu_count(). Also applies to parallel test execution (by definingCTEST_PARALLEL_LEVEL
environment variable).build_type (Optional, Defaulted to
None
): Force the build type instead of taking the value from the settings. Note thatCMAKE_BUILD_TYPE
will not be declared when using CMake multi-configuration generators such as Visual Studio or XCode as it will not have effect.toolset (Optional, Defaulted to
None
): Specify a toolset for Visual Studio.make_program (Optional, Defaulted to
None
): Indicate path tomake
.set_cmake_flags (Optional, Defaulted to
None
): Whether or not to set CMake flags likeCMAKE_CXX_FLAGS
,CMAKE_C_FLAGS
, etc.msbuild_verbosity (Optional, Defaulted to
minimal
): verbosity level for MSBuild (in case of Visual Studio generator). Set this parameter toNone
to avoid using it in the command line.cmake_program (Optional, Defaulted to
None
): Path to the custom cmake executable.generator_platform (Optional, Defaulted to
None
): Generator platform name or none to autodetect (-A cmake option).append_vcvars (Optional, Defaulted to
False
): When a Visual Studio environment is activated by the build helper, append it to respect existing environment.CMake
helper sometimes, like when using the Ninja generator, needs to callvcvars
to set the VS environment. By default thevcvars
is pre-pended to the environment, taking precedence. Withappend_vcvars=True
, thevcvars
will append to the end of the environment (for “list” environment variables, likePATH
), instead of pre-pending, so the existing environment takes precedence.
Attributes
generator
Specifies a custom CMake generator to use, see also cmake-generators documentation.
generator_platform
Specifies a custom CMake generator platform to use, see also CMAKE_GENERATOR_PLATFORM documentation.
verbose
Defaulted to: False
Set it to True
or False
to automatically set the definition CMAKE_VERBOSE_MAKEFILE
.
from conans import ConanFile, CMake
class ExampleConan(ConanFile):
...
def build(self):
cmake = CMake(self)
cmake.verbose = True
cmake.configure()
cmake.build()
build_folder (Read only)
Build folder where the configure()
and build()
methods will be called.
build_type [Deprecated]
Build type can be forced with this variable instead of taking it from the settings.
flags (Read only)
Flag conversion of definitions
to be used in the command line invocation (-D
).
is_multi_configuration (Read only)
Indicates whether the generator selected allows builds with multi configuration: Release, Debug… Multi configuration generators are Visual Studio and Xcode ones.
command_line (Read only)
Arguments and flags calculated by the build helper that will be applied. It indicates the generator, the Conan definitions and the flags converted from the specified Conan settings. For example:
-G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ... -DCONAN_C_FLAGS=-m64 -Wno-dev
build_config (Read only)
Value for --config option for Multi-configuration IDEs. This flag will only be set if the generator is_multi_configuration
and build_type
was not forced in constructor class.
An example of the value of this property could be:
--config Release
parallel
Defaulted to: True
Run CMake process in parallel for compilation, installation and testing. This is translated into the proper command line argument:
For Unix Makefiles
it is -jX
and for Visual Studio
it is /m:X
.
However, the parallel executing can be changed for testing like this:
cmake = CMake(self)
cmake.configure()
cmake.build() # 'parallel' is enabled by default
cmake.parallel = False
cmake.test()
In the case of cmake.test()
this flag sets the CTEST_PARALLEL_LEVEL
variable to the according value in tools.cpu_count().
definitions
The CMake helper will automatically append some definitions based on your settings:
Variable |
Description |
---|---|
ANDROID_ABI |
Just alias for CMAKE_ANDROID_ARCH_ABI |
ANDROID_NDK |
Defined when one of ANDROID_NDK_ROOT or ANDROID_NDK_HOME environment variables presented |
BUILD_SHARED_LIBS |
Only if your recipe has a |
CMAKE_ANDROID_ARCH_ABI |
Set to a suitable value if cross-building to an Android is detected |
CMAKE_BUILD_TYPE |
Debug, Release… from |
CMAKE_EXPORT_NO_PACKAGE_REGISTRY |
Defined by default to disable the package registry |
CMAKE_MODULE_PATH |
Set to |
CMAKE_OSX_ARCHITECTURES |
|
CMAKE_PREFIX_PATH |
Set to |
CMAKE_SYSTEM_NAME |
Set to |
CMAKE_SYSROOT |
Defined if CONAN_CMAKE_SYSROOT is defined as environment variable |
CMAKE_SYSTEM_VERSION |
Set to |
CONAN_CMAKE_CXX_EXTENSIONS |
Set to |
CONAN_CMAKE_CXX_STANDARD |
Set to the |
CONAN_CMAKE_FIND_ROOT_PATH |
Definition set only if same environment variable is declared by user |
CONAN_CMAKE_FIND_ROOT_PATH_MODE_INCLUDE |
Definition set only if same environment variable is declared by user |
CONAN_CMAKE_FIND_ROOT_PATH_MODE_LIBRARY |
Definition set only if same environment variable is declared by user |
CONAN_CMAKE_FIND_ROOT_PATH_MODE_PROGRAM |
Definition set only if same environment variable is declared by user |
CONAN_CMAKE_POSITION_INDEPENDENT_CODE |
Set when |
CONAN_CMAKE_SYSTEM_PROCESSOR |
Definition set only if same environment variable is declared by user |
CONAN_COMPILER |
Conan internal variable to check the compiler |
CONAN_CXX_FLAGS |
Set to |
CONAN_C_FLAGS |
Set to |
CONAN_EXPORTED |
Defined when CMake is called using Conan CMake helper |
CONAN_IN_LOCAL_CACHE |
|
CONAN_LIBCXX |
Set to |
CONAN_LINK_RUNTIME |
Set to the runtime value from |
CONAN_SHARED_LINKER_FLAGS |
Set to |
CONAN_STD_CXX_FLAG |
Set to the flag corresponding to the C++ standard defined in |
There are some definitions set to be used later on the the install()
step too:
Variable |
Description |
---|---|
CMAKE_INSTALL_BINDIR |
Set to bin inside the package folder. |
CMAKE_INSTALL_DATAROOTDIR |
Set to share inside the package folder. |
CMAKE_INSTALL_INCLUDEDIR |
Set to include inside the package folder. |
CMAKE_INSTALL_LIBDIR |
Set to lib inside the package folder. |
CMAKE_INSTALL_LIBEXECDIR |
Set to bin inside the package folder. |
CMAKE_INSTALL_OLDINCLUDEDIR |
Set to include inside the package folder. |
CMAKE_INSTALL_PREFIX |
Set to |
CMAKE_INSTALL_SBINDIR |
Set to bin inside the package folder. |
But you can change the automatic definitions after the CMake()
object creation using the definitions
property or even add your own
ones:
from conans import ConanFile, CMake
class ExampleConan(ConanFile):
...
def build(self):
cmake = CMake(self)
cmake.definitions["CMAKE_SYSTEM_NAME"] = "Generic"
cmake.definitions["MY_CUSTOM_DEFINITION"] = "OFF"
cmake.configure()
cmake.build()
cmake.install() # Build --target=install
Note that definitions changed after the configure()
call will not take effect later on the build()
, test()
or
install()
ones.
Methods
configure()
def configure(self, args=None, defs=None, source_dir=None, build_dir=None,
source_folder=None, build_folder=None, cache_build_folder=None,
pkg_config_paths=None)
Configures CMake project with the given parameters.
- Parameters:
args (Optional, Defaulted to
None
): A list of additional arguments to be passed to thecmake
command. Each argument will be escaped according to the current shell. No extra arguments will be added ifargs=None
defs (Optional, Defaulted to
None
): A dict that will be converted to a list of CMake command line variable definitions of the form-DKEY=VALUE
. Each value will be escaped according to the current shell and can be eitherstr
,bool
or of numeric typesource_dir (Optional, Defaulted to
None
): [DEPRECATED] Usesource_folder
instead. CMake’s source directory where CMakeLists.txt is located. The default value is thebuild
folder ifNone
is specified (or thesource
folder ifno_copy_source
is specified). Relative paths are allowed and will be relative tobuild_folder
.build_dir (Optional, Defaulted to
None
): [DEPRECATED] Usebuild_folder
instead. CMake’s output directory. The default value is the packagebuild
root folder ifNone
is specified. TheCMake
object will storebuild_folder
internally for subsequent calls tobuild()
.source_folder: CMake’s source directory where
CMakeLists.txt
is located. The default value is theself.source_folder
. Relative paths are allowed and will be relative toself.source_folder
.build_folder: CMake’s output directory. The default value is the
self.build_folder
ifNone
is specified. TheCMake
object will storebuild_folder
internally for subsequent calls tobuild()
.cache_build_folder (Optional, Defaulted to
None
): Use the given subfolder as build folder when building the package in the local cache. This argument doesn’t have effect when the package is being built in user folder with conan build but overrides build_folder when working in the local cache. See self.in_local_cache.pkg_config_paths (Optional, Defaulted to
None
): Specify folders (in a list) of relative paths to the install folder or absolute ones where to find*.pc
files (by using the env varPKG_CONFIG_PATH
). IfNone
is specified but the conanfile is using thepkg_config
generator, theself.install_folder
will be added to thePKG_CONFIG_PATH
in order to locate the pc files of the requirements of the conanfile.
build()
def build(self, args=None, build_dir=None, target=None)
Builds CMake project with the given parameters.
- Parameters:
args (Optional, Defaulted to
None
): A list of additional arguments to be passed to thecmake
command. Each argument will be escaped according to the current shell. No extra arguments will be added ifargs=None
build_dir (Optional, Defaulted to
None
): CMake’s output directory. IfNone
is specified thebuild_dir
fromconfigure()
will be used.target (Optional, Defaulted to
None
): Specifies the target to execute. The default all target will be built ifNone
is specified."install"
can be used to relocate files to aid packaging.
test()
def test(args=None, build_dir=None, target=None, output_on_failure=False)
Build CMake test target (could be RUN_TESTS in multi-config projects or test
in single-config
projects), which usually means building and running unit tests. When this function is called
CONAN_RUN_TESTS will be evaluated to check if tests should run.
- Parameters:
args (Optional, Defaulted to
None
): A list of additional arguments to be passed to thecmake
command. Each argument will be escaped according to the current shell. No extra arguments will be added ifargs=None
.build_dir (Optional, Defaulted to
None
): CMake’s output directory. IfNone
is specified thebuild_folder
fromconfigure()
will be used.target (Optional, default to
None
). Alternative target name for running the tests. If not defined RUN_TESTS ortest
will be used.output_on_failure (Optional, default to
False
). Enables ctest to show output of failed tests by definingCTEST_OUTPUT_ON_FAILURE
environment variable (same effect asctest --output-on-failure
).
This method can be globally skipped by tools.build:skip_test
[conf], or CONAN_RUN_TESTS
environment variable.
install()
def install(args=None, build_dir=None)
Installs CMake project with the given parameters.
- Parameters:
args (Optional, Defaulted to
None
): A list of additional arguments to be passed to thecmake
command. Each argument will be escaped according to the current shell. No extra arguments will be added ifargs=None
.build_dir (Optional, Defaulted to
None
): CMake’s output directory. IfNone
is specified thebuild_folder
fromconfigure()
will be used.
patch_config_paths()
def patch_config_paths()
Warning
This is a deprecated feature. Please refer to the Migration Guidelines to find the feature that replaced this one.
This method changes references to the absolute path of the installed package in exported CMake config files to the appropriate Conan variable. Method also changes references to other packages installation paths in export CMake config files to Conan variable with their installation roots. This makes most CMake config files portable.
For example, if a package foo installs a file called fooConfig.cmake to be used by cmake’s find_package()
method, normally this file
will contain absolute paths to the installed package folder, for example it will contain a line such as:
SET(Foo_INSTALL_DIR /home/developer/.conan/data/foo/1.0.0/...)
This will cause cmake’s find_package()
method to fail when someone else installs the package via Conan. This function will replace such
paths to:
SET(Foo_INSTALL_DIR ${CONAN_FOO_ROOT})
Which is a variable that is set by conanbuildinfo.cmake, so that find_package()
now correctly works on this Conan package.
For dependent packages method replaces lines with references to dependencies installation paths such as:
SET_TARGET_PROPERTIES(foo PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "/home/developer/.conan/data/bar/1.0.0/user/channel/id/include")
to following lines:
SET_TARGET_PROPERTIES(foo PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${CONAN_BAR_ROOT}/include")
If the install()
method of the CMake object in the conanfile is used, this function should be called after that invocation. For
example:
def build(self):
cmake = CMake(self)
cmake.configure()
cmake.build()
cmake.install()
cmake.patch_config_paths()
get_version()
@staticmethod
def get_version()
Returns the CMake version in a conans.model.Version
object as it is evaluated by the
command line. Will raise if cannot resolve it to valid version.
Environment variables
There are some environment variables that will also affect the CMake()
helper class. Check them in the
CMAKE RELATED VARIABLES section.
Example
The following example of conanfile.py
shows you how to manage a project with conan and CMake.
from conans import ConanFile, CMake
class SomePackage(ConanFile):
name = "somepkg"
version = "1.0.0"
settings = "os", "compiler", "build_type", "arch"
generators = "cmake"
def configure_cmake(self):
cmake = CMake(self)
# put definitions here so that they are re-used in cmake between
# build() and package()
cmake.definitions["SOME_DEFINITION_NAME"] = "On"
cmake.configure()
return cmake
def build(self):
cmake = self.configure_cmake()
cmake.build()
# run unit tests after the build
cmake.test()
# run custom make command
self.run("make -j3 check)
def package(self):
cmake = self.configure_cmake()
cmake.install()
Default used generators
When a compiler or its version is not detected, the CMake helper uses a default generator based on the platform operating system.
For Unix systems it generates Unix Makefiles
. For Windows there is no default generator, it will be detected by CMake automatically.