CMakeToolchain¶
CMakeToolchain
是 CMake 的工具链生成器。它生成工具链文件,可用于在命令行调用 CMake 时,通过 -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake
进行使用。此生成器将当前的包配置、设置和选项转换为 CMake 工具链语法。
它可以声明为
from conan import ConanFile
class Pkg(ConanFile):
generators = "CMakeToolchain"
或在 generate()
方法中完全实例化
from conan import ConanFile
from conan.tools.cmake import CMakeToolchain
class App(ConanFile):
settings = "os", "arch", "compiler", "build_type"
requires = "hello/0.1"
generators = "CMakeDeps"
options = {"shared": [True, False], "fPIC": [True, False]}
default_options = {"shared": False, "fPIC": True}
def generate(self):
tc = CMakeToolchain(self)
tc.variables["MYVAR"] = "MYVAR_VALUE"
tc.preprocessor_definitions["MYDEFINE"] = "MYDEF_VALUE"
tc.generate()
注意
CMakeToolchain
旨在与 CMakeDeps
依赖项生成器一起运行。请勿将其他 CMake 传统生成器(如 cmake
或 cmake_paths
)与其一起使用。
生成的文件¶
这将通过 conan install
(或在缓存中构建包时)生成以下文件,其中包含 generate()
方法中提供的信息以及从当前 settings
转换的信息
conan_toolchain.cmake:包含 Conan 设置到 CMake 变量的转换。此文件中将定义的一些内容有
CMake 生成器平台和生成器工具集的定义
根据
fPIC
选项定义CMAKE_POSITION_INDEPENDENT_CODE
。根据需要定义 C++ 标准
定义 C++ 使用的标准库
在 OSX 中禁用 rpaths
在 Windows 上使用 Visual Studio 时定义
CMAKE_VS_DEBUGGER_ENVIRONMENT
。这会设置PATH
环境变量以指向包含 DLL 的目录,从而允许直接从 Visual Studio IDE 进行调试而无需复制 DLL(需要 CMake 3.27)。定义
CONAN_RUNTIME_LIB_DIRS
以允许收集运行时依赖项(共享库),详细信息见下文。
conanvcvars.bat:在某些情况下,Visual Studio 环境需要正确定义才能进行构建,例如使用 Ninja 或 NMake 生成器时。如果需要,
CMakeToolchain
将生成此脚本,从而更容易定义正确的 Visual Studio 提示。CMakePresets.json:此工具链生成一个标准的 CMakePresets.json 文件。有关更多信息,请参阅此处的文档。它当前使用 JSON 模式的“3”版本。Conan 在 JSON 文件中添加了 configure、build 和 test 预设条目
- configurePresets 存储以下信息
要使用的 generator。
conan_toolchain.cmake 的路径。
与指定设置对应的缓存变量,如果不在工具链中指定则无法工作。
用于单配置生成器的 CMAKE_BUILD_TYPE 变量。
当配置 tools.build:skip_test 为真时,BUILD_TESTING 变量设置为 OFF。
一个环境部分,设置与 VirtualBuildEnv 相关的所有环境信息(如果适用)。此环境可以通过在 recipe 的 generate() 方法中通过 CMakeToolchain.presets_build_environment 属性传递环境来修改。可以使用 tools.cmake.cmaketoolchain:presets_environment 配置跳过此部分的生成。
默认情况下,预设名称将为 conan-xxxx,但可以使用 CMakeToolchain.presets_prefix = “conan” 属性自定义“conan-”前缀。
预设名称由 layout() self.folders.build_folder_vars 定义控制,它可以包含设置、选项、
self.name
和self.version
以及常量const.xxx
的列表,例如 [“settings.compiler”, “settings.arch”, “options.shared”, “const.myname”]。如果 CMake 被发现为直接 tool_requires 依赖项,或者如果设置了 tools.cmake:cmake_program,则配置预设将包含一个 cmakeExecutable 字段。此字段表示用于此预设的 CMake 可执行文件的路径。如 CMake 文档所述,此字段保留供 IDE 使用,CMake 本身不使用。
- buildPresets 存储以下信息
与此构建预设关联的 configurePreset。
- testPresets 存储以下信息
与此构建预设关联的 configurePreset。
一个环境部分,设置与 VirtualRunEnv 相关的所有环境信息(如果适用)。此环境可以通过在 recipe 的 generate() 方法中通过 CMakeToolchain.presets_run_environment 属性传递环境来修改。请注意,由于此预设继承自 configurePreset,它也将继承其环境。可以使用 `tools.cmake.cmaketoolchain:presets_environment` 配置跳过此部分的生成。
CMakeUserPresets.json:如果在 recipe 中声明了
layout()
并且在conanfile.source_folder
文件夹中找到了CMakeLists.txt
文件,则将生成一个CMakeUserPresets.json
文件(如果尚不存在),其中自动包含CMakePresets.json
(位于conanfile.generators_folder
),以允许您的 IDE(Visual Studio、Visual Studio Code、CLion...)或cmake
工具定位CMakePresets.json
。生成的CMakeUserPresets.json
的位置可以通过user_presets_path
属性进一步调整,如下文所述。生成的CMakeUserPresets.json
的版本模式是“4”,需要 CMake >= 3.23。此文件的文件名可以通过CMakeToolchain.user_presets_path = "CMakeUserPresets.json"`
属性进行配置,因此如果您想生成一个“ConanPresets.json”而不是从自己的文件中包含,您可以在generate()
方法中定义tc.user_presets_path = "ConanPresets.json"
。有关完整示例,请参阅扩展您自己的 CMake 预设。注意: 如果
CMakeUserPresets.json
已存在且不是由 Conan 生成的,Conan 将跳过生成该文件。注意: 要列出所有可用的预设,请使用
cmake --list-presets
命令
注意
生成的 CMakeUserPresets.json
的版本模式为 4(兼容 CMake >= 3.23),CMakePresets.json
的模式为 3(兼容 CMake >= 3.21)。
CONAN_RUNTIME_LIB_DIRS¶
生成的文件 conan_toolchain.cmake
中的此变量包含主机上下文中所有依赖项的运行时库(如 DLL)的目录列表。这旨在用于依赖 CMake 功能收集共享库以创建可重定位包,如下例所示。
只需将 CONAN_RUNTIME_LIB_DIRS
变量传递给 install(RUNTIME_DEPENDENCY_SET ...)`
调用的 DIRECTORIES
参数。
install(RUNTIME_DEPENDENCY_SET my_app_deps
PRE_EXCLUDE_REGEXES
[[api-ms-win-.*]]
[[ext-ms-.*]]
[[kernel32\.dll]]
[[libc\.so\..*]] [[libgcc_s\.so\..*]] [[libm\.so\..*]] [[libstdc\+\+\.so\..*]]
POST_EXCLUDE_REGEXES
[[.*/system32/.*\.dll]]
[[^/lib.*]]
[[^/usr/lib.*]]
DIRECTORIES ${CONAN_RUNTIME_LIB_DIRS}
)
自定义¶
preprocessor_definitions¶
此属性允许为多种配置(Debug、Release 等)定义编译器预处理器定义。
def generate(self):
tc = CMakeToolchain(self)
tc.preprocessor_definitions["MYDEF"] = "MyValue"
tc.preprocessor_definitions.debug["MYCONFIGDEF"] = "MyDebugValue"
tc.preprocessor_definitions.release["MYCONFIGDEF"] = "MyReleaseValue"
# Setting to None will add the definition with no value
tc.preprocessor_definitions["NOVALUE_DEF"] = None
tc.generate()
这将转换为
conan_toolchain.cmake
文件中MYDEF
的一个add_compile_definitions()
定义。conan_toolchain.cmake
文件中使用 cmake 生成器表达式的一个add_compile_definitions()
定义,为不同配置使用不同的值。
cache_variables¶
此属性允许定义 CMake 缓存变量。这些变量与 variables
不同,是单配置的。它们将存储在 CMakePresets.json
文件中(在 configurePreset 的 cacheVariables 中),并将在使用 CMake() 构建助手调用 cmake.configure
时通过 -D
参数应用。
def generate(self):
tc = CMakeToolchain(self)
tc.cache_variables["foo"] = True
tc.cache_variables["foo2"] = False
tc.cache_variables["var"] = "23"
分配给 cache_variable
的布尔值将被转换为 CMake 中的 ON
和 OFF
符号。
variables¶
此属性允许定义 CMake 变量,用于多种配置(Debug、Release 等)。这些变量应用于定义与工具链相关的内容,在大多数情况下,您可能希望使用 cache_variables。此外,请注意,由于这些变量定义在 *conan_toolchain.cmake* 文件中,并且工具链被 CMake 加载多次,因此这些变量的定义也会在这些点进行。
def generate(self):
tc = CMakeToolchain(self)
tc.variables["MYVAR"] = "MyValue"
tc.variables.debug["MYCONFIGVAR"] = "MyDebugValue"
tc.variables.release["MYCONFIGVAR"] = "MyReleaseValue"
tc.generate()
这将转换为
conan_toolchain.cmake
文件中MYVAR
的一个set()
定义。conan_toolchain.cmake
文件中使用 cmake 生成器表达式的一个set()
定义,为不同配置使用不同的值。
分配给变量的布尔值将被转换为 CMake 中的 ON
和 OFF
符号
def generate(self):
tc = CMakeToolchain(self)
tc.variables["FOO"] = True
tc.variables["VAR"] = False
tc.generate()
将生成语句:set(FOO ON ...)
和 set(VAR OFF ...)
。
user_presets_path¶
此属性允许指定生成的 CMakeUserPresets.json
文件的位置。接受的值有
一个绝对路径
相对于
self.source_folder
的路径布尔值
False
,以完全禁止文件的生成。
例如,我们可以通过以下方式阻止生成器创建 CMakeUserPresets.json
def generate(self):
tc = CMakeToolchain(self)
tc.user_presets_path = False
tc.generate()
也可以使用 tools.cmake.cmaketoolchain:user_presets
实验性配置来更改 CMakeUserPresets.json
文件的名称和位置。将其设置为空字符串将完全禁用文件生成。请查看conf 部分以获取更多信息。
presets_build_environment, presets_run_environment¶
这些属性分别通过分配一个 Environment 来启用修改与预设关联的构建和运行环境。这可以在 generate() 方法中完成。
例如,您可以覆盖构建环境中已设置的环境变量的值
def generate(self):
buildenv = VirtualBuildEnv(self)
buildenv.environment().define("MY_BUILD_VAR", "MY_BUILDVAR_VALUE_OVERRIDDEN")
buildenv.generate()
tc = CMakeToolchain(self)
tc.presets_build_environment = buildenv.environment()
tc.generate()
或者生成一个新环境并与现有环境组合
def generate(self):
runenv = VirtualRunEnv(self)
runenv.environment().define("MY_RUN_VAR", "MY_RUNVAR_SET_IN_GENERATE")
runenv.generate()
env = Environment()
env.define("MY_ENV_VAR", "MY_ENV_VAR_VALUE")
env = env.vars(self, scope="run")
env.save_script("other_env")
tc = CMakeToolchain(self)
tc.presets_run_environment = runenv.environment().compose_env(env)
tc.generate()
额外编译标志¶
您可以使用以下属性向工具链追加额外编译标志
extra_cxxflags (默认为
[]
) 用于额外的 cxxflagsextra_cflags (默认为
[]
) 用于额外的 cflagsextra_sharedlinkflags (默认为
[]
) 用于额外的共享链接标志extra_exelinkflags (默认为
[]
) 用于额外的 exe 链接标志
注意
标志优先级顺序:在 tools.build 配置中指定的标志,例如 cxxflags、cflags、sharedlinkflags 和 exelinkflags,将始终优先于 CMakeToolchain 属性设置的标志。
presets_prefix¶
默认情况下是 "conan"
,它将生成名为“conan-xxxx”的 CMake 预设。这样做是为了避免与用户自己的预设可能发生的名称冲突。
absolute_paths¶
默认情况下,CMakeToolchain
将生成相对路径。例如,CMakeUserPresets.json
将包含一个指向所包含的 CMakePresets.json
的相对路径(这两个文件都由 CMakeToolchain
生成),而 CMakePresets.json
文件将在其 toolchainFile
字段中包含一个指向 conan_toolchain.cmake
文件的相对路径,该路径相对于构建文件夹,如 CMake 预设文档所指定。
如果出于某种原因需要使用绝对路径,可以通过以下方式实现
def generate(self):
tc = CMakeToolchain(self)
tc.absolute_paths = True
tc.generate()
使用自定义工具链文件¶
有两种提供自定义 CMake 工具链文件的方法
conan_toolchain.cmake
文件可以完全跳过并替换为用户文件,通过定义tools.cmake.cmaketoolchain:toolchain_file=<filepath>
配置值。请注意,这种方法将所有工具链责任转移到用户提供的工具链,但如果没有一些帮助,定位依赖项所需的xxx-config.cmake
文件可能会很困难。因此,在大多数情况下,建议使用下面的tools.cmake.cmaketoolchain:user_toolchain
,如果需要,可以使用tools.cmake.cmaketoolchain:enabled_blocks
。可以通过使用下面描述的
user_toolchain
块,并定义tools.cmake.cmaketoolchain:user_toolchain=["<filepath>"]
配置值,将自定义用户工具链文件添加到(从)conan_toolchain.cmake
文件中。配置
tools.cmake.cmaketoolchain:user_toolchain=["<filepath>"]
可以在global.conf
中定义。但也可以为您的工具链创建 Conan 包并使用self.conf_info
声明工具链文件import os from conan import ConanFile class MyToolchainPackage(ConanFile): ... def package_info(self): f = os.path.join(self.package_folder, "mytoolchain.cmake") self.conf_info.define("tools.cmake.cmaketoolchain:user_toolchain", [f])
如果您将上一个包声明为
tool_require
,则工具链将自动应用。如果您定义了多个
tool_requires
,您可以轻松地使用每个的append
方法将所有用户工具链值一起追加,例如import os from conan import ConanFile class MyToolRequire(ConanFile): ... def package_info(self): f = os.path.join(self.package_folder, "mytoolchain.cmake") # Appending the value to any existing one self.conf_info.append("tools.cmake.cmaketoolchain:user_toolchain", f)
因此,它们将由您的
CMakeToolchain
生成器自动应用,而无需编写任何额外代码from conan import ConanFile from conan.tools.cmake import CMake class Pkg(ConanFile): settings = "os", "compiler", "arch", "build_type" exports_sources = "CMakeLists.txt" tool_requires = "toolchain1/0.1", "toolchain2/0.1" generators = "CMakeToolchain" def build(self): cmake = CMake(self) cmake.configure()
注意
重要注意事项
在大多数情况下,
tools.cmake.cmaketoolchain:user_toolchain
将优于tools.cmake.cmaketoolchain:toolchain_file
user_toolchain
文件可以定义用于交叉构建的变量,例如CMAKE_SYSTEM_NAME
、CMAKE_SYSTEM_VERSION
和CMAKE_SYSTEM_PROCESSOR
。如果在用户工具链文件中定义了这些变量,它们将受到尊重,并且conan_toolchain.cmake
推导的变量将不会覆盖用户定义的变量。如果用户工具链文件中未定义这些变量,则将使用 Conan 自动推导的变量。在user_toolchain
文件中定义的这些变量也将比配置定义的变量(如tools.cmake.cmaketoolchain:system_name
)具有更高的优先级。tools.cmake.cmaketoolchain:enabled_blocks
的用法可以与tools.cmake.cmaketoolchain:user_toolchain
一起使用,以仅启用某些块,但避免 CMakeToolchain 覆盖用户工具链文件中定义的 CMake 值。
扩展和高级定制¶
CMakeToolchain
实现了强大的扩展和定制生成的工具链文件的能力。
内容由可定制的 blocks
组织。以下预定义块可用,并按此顺序添加
user_toolchain:允许从
conan_toolchain.cmake
文件中包含用户工具链。如果定义了配置tools.cmake.cmaketoolchain:user_toolchain=["xxxx", "yyyy"]
,其值将作为conan_toolchain.cmake
中的第一行:include(xxx)\ninclude(yyyy)
。generic_system:定义
CMAKE_SYSTEM_NAME
、CMAKE_SYSTEM_VERSION
、CMAKE_SYSTEM_PROCESSOR
、CMAKE_GENERATOR_PLATFORM
、CMAKE_GENERATOR_TOOLSET
compilers:为不同的语言定义
CMAKE_<LANG>_COMPILER
,如tools.build:compiler_executables
配置所定义。android_system:定义
ANDROID_PLATFORM
、ANDROID_STL
、ANDROID_ABI
并包含ANDROID_NDK_PATH/build/cmake/android.toolchain.cmake
,其中ANDROID_NDK_PATH
定义在tools.android:ndk_path
配置值中。apple_system:为 Apple 系统定义
CMAKE_OSX_ARCHITECTURES
(参见通用二进制文件部分)、CMAKE_OSX_SYSROOT
。fpic:当存在
options.fPIC
时,定义CMAKE_POSITION_INDEPENDENT_CODE
。arch_flags:必要时定义 C/C++ 标志,如
-m32, -m64
。linker_scripts:定义任何提供的链接器脚本的标志。
libcxx:必要时定义
-stdlib=libc++
标志以及_GLIBCXX_USE_CXX11_ABI
。vs_runtime:将
CMAKE_MSVC_RUNTIME_LIBRARY
变量定义为多配置的生成器表达式。vs_debugger_environment:定义来自依赖项“bindirs”文件夹的
CMAKE_VS_DEBUGGER_ENVIRONMENT
,专用于 Visual Studio。cppstd:定义
CMAKE_CXX_STANDARD
、CMAKE_CXX_EXTENSIONS
parallel:为 Visual 定义
/MP
并行构建标志。extra_flags:从
tools.build:cxxflags
、tools.build:cflags
、tools.build:defines
、tools.build:sharedlinkflags
等添加额外定义、编译和链接标志。cmake_flags_init:根据先前定义的 Conan 变量定义
CMAKE_XXX_FLAGS
变量。上述块仅定义CONAN_XXX
变量,而此块将定义 CMake 变量,如set(CMAKE_CXX_FLAGS_INIT "${CONAN_CXX_FLAGS}" CACHE STRING "" FORCE)`
。extra_variables:从
tools.cmake.cmaketoolchain:extra_variables
定义额外 CMake 变量try_compile:如果定义了
IN_TRY_COMPILE
CMake 属性,则停止处理工具链,跳过此块以下的块。find_paths:定义
CMAKE_FIND_PACKAGE_PREFER_CONFIG
、CMAKE_MODULE_PATH
、CMAKE_PREFIX_PATH
,以便找到CMakeDeps
生成的文件。pkg_config:根据
tools.gnu:pkg_config
定义PKG_CONFIG_EXECUTABLE
,并将CMAKE_CURRENT_LIST_DIR
添加到ENV{PKG_CONFIG_PATH}
,以便 pkg-config 查找生成的 .pc 文件。rpath:定义
CMAKE_SKIP_RPATH
。默认禁用,如果需要激活CMAKE_SKIP_RPATH
,则需要定义self.blocks["rpath"].skip_rpath=True
。shared:定义
BUILD_SHARED_LIBS
。output_dirs:定义
CMAKE_INSTALL_XXX
变量。CMAKE_INSTALL_PREFIX:设置为
package_folder
,因此如果运行“cmake install”操作,则工件将转到该位置。CMAKE_INSTALL_BINDIR、CMAKE_INSTALL_SBINDIR 和 CMAKE_INSTALL_LIBEXECDIR:默认设置为
bin
。CMAKE_INSTALL_LIBDIR:默认设置为
lib
。CMAKE_INSTALL_INCLUDEDIR 和 CMAKE_INSTALL_OLDINCLUDEDIR:默认设置为
include
。CMAKE_INSTALL_DATAROOTDIR:默认设置为
res
。
如果要更改默认值,请在
layout()
方法中调整cpp.package
对象def layout(self): ... # For CMAKE_INSTALL_BINDIR, CMAKE_INSTALL_SBINDIR and CMAKE_INSTALL_LIBEXECDIR, takes the first value: self.cpp.package.bindirs = ["mybin"] # For CMAKE_INSTALL_LIBDIR, takes the first value: self.cpp.package.libdirs = ["mylib"] # For CMAKE_INSTALL_INCLUDEDIR, CMAKE_INSTALL_OLDINCLUDEDIR, takes the first value: self.cpp.package.includedirs = ["myinclude"] # For CMAKE_INSTALL_DATAROOTDIR, takes the first value: self.cpp.package.resdirs = ["myres"]
注意
在
package_info()
方法中更改 self.cpp_info 无效,需要改为定义self.cpp.package
。variables:从
CMakeToolchain.variables
属性定义 CMake 变量。preprocessor:从
CMakeToolchain.preprocessor_definitions
属性定义预处理器指令
自定义内容块¶
每个块都可以以不同方式进行定制(定制后请记住调用 tc.generate()
)
# tc.generate() should be called at the end of every one
# remove an existing block, the generated conan_toolchain.cmake
# will not contain code for that block at all
def generate(self):
tc = CMakeToolchain(self)
tc.blocks.remove("generic_system")
# remove several blocks
def generate(self):
tc = CMakeToolchain(self)
tc.blocks.remove("generic_system", "cmake_flags_init")
# LEGACY: keep one block, remove all the others
# If you want to generate conan_toolchain.cmake with only that
# block. Use "tc.blocks.enabled()" instead
def generate(self):
tc = CMakeToolchain(self)
# this still leaves blocks "variables" and "preprocessor"
# use "tc.blocks.enabled()"" instead
tc.blocks.select("generic_system")
# LEGACY: keep several blocks, remove the other blocks
# Use "tc.blocks.enabled()" instead
def generate(self):
tc = CMakeToolchain(self)
# this still leaves blocks "variables" and "preprocessor"
# use "tc.blocks.enabled()" instead
tc.blocks.select("generic_system", "cmake_flags_init")
# keep several blocks, remove the other blocks
# This can be done from configuration with
# tools.cmake.cmaketoolchain:enabled_blocs
def generate(self):
tc = CMakeToolchain(self)
# Discard all the other blocks except ``generic_system``
tc.blocks.enabled("generic_system")
# iterate blocks
def generate(self):
tc = CMakeToolchain(self)
for block_name in tc.blocks.keys():
# do something with block_name
for block_name, block in tc.blocks.items():
# do something with block_name and block
# modify the template of an existing block
def generate(self):
tc = CMakeToolchain(self)
tmp = tc.blocks["generic_system"].template
new_tmp = tmp.replace(...) # replace, fully replace, append...
tc.blocks["generic_system"].template = new_tmp
# modify one or more variables of the context
def generate(self):
tc = CMakeToolchain(conanfile)
# block.values is the context dictionary
toolset = tc.blocks["generic_system"].values["toolset"]
tc.blocks["generic_system"].values["toolset"] = "other_toolset"
# modify the whole context values
def generate(self):
tc = CMakeToolchain(conanfile)
tc.blocks["generic_system"].values = {"toolset": "other_toolset"}
# modify the context method of an existing block
import types
def generate(self):
tc = CMakeToolchain(self)
generic_block = toolchain.blocks["generic_system"]
def context(self):
assert self # Your own custom logic here
return {"toolset": "other_toolset"}
generic_block.context = types.MethodType(context, generic_block)
# completely replace existing block
from conan.tools.cmake import CMakeToolchain
def generate(self):
tc = CMakeToolchain(self)
# this could go to a python_requires
class MyGenericBlock:
template = "HelloWorld"
def context(self):
return {}
tc.blocks["generic_system"] = MyGenericBlock
# add a completely new block
from conan.tools.cmake import CMakeToolchain
def generate(self):
tc = CMakeToolchain(self)
# this could go to a python_requires
class MyBlock:
template = "Hello {{myvar}}!!!"
def context(self):
return {"myvar": "World"}
tc.blocks["mynewblock"] = MyBlock
可以通过配置文件中的配置来选择哪些块处于活动状态,使用 tools.cmake.cmaketoolchain:enabled_blocks
配置。这是一个块列表,因此这样做
[conf]
tools.cmake.cmaketoolchain:enabled_blocks=["generic_system"]
将只保留 generic_system
块,并丢弃所有其他块。此功能可用于例如用户提供自己的工具链文件时,他们不需要 Conan CMakeToolchain
定义任何标志或 CMake 变量,除了必要的路径以便找到依赖项。在这种情况下,应该可以这样做
[conf]
tools.cmake.cmaketoolchain:user_toolchain+=my_user_toolchain.cmake
tools.cmake.cmaketoolchain:enabled_blocks=["find_paths"]
有关这些块的更多信息,请参阅源代码。
查找依赖项路径¶
生成的 conan_toolchain.cmake
在其 find_paths
块中包含变量信息,例如 CMAKE_PROGRAM_PATH
、CMAKE_LIBRARY_PATH
、CMAKE_INCLUDE_PATH
等,这些变量允许 CMake 运行 find_program()
、find_file()
和其他特殊的“查找器”例程,这些例程在没有通过整体推荐的 find_package()
进行显式包和目标定义的情况下查找工件。
有了新的孵化中的 CMakeConfigDeps
,conan_toolchain.cmake
块 find_paths
不再自己定义信息,而是加载由 CMakeConfigDeps
生成器生成的新文件 conan_cmakedeps_paths.cmake
。这样,创建依赖项信息的责任就归 CMakeConfigDeps
生成器所有,并且在某些无法传递工具链的场景中可以使用该新文件。
交叉构建¶
generic_system
块包含一些基本的交叉构建功能。在一般情况下,用户希望提供自己的用户工具链来定义所有具体内容,这可以通过配置 tools.cmake.cmaketoolchain:user_toolchain
来完成。如果定义了此配置值,generic_system
块将包含提供的文件,但不会进一步定义任何用于交叉构建的 CMake 变量。
如果未定义 user_toolchain
且 Conan 检测到正在交叉构建(因为构建和主机配置文件包含不同的操作系统或架构),它将尝试定义以下变量
CMAKE_SYSTEM_NAME
:如果定义了tools.cmake.cmaketoolchain:system_name
配置,则使用该值,否则将尝试自动检测。此块将考虑 Android 系统(由其他块管理)以及 x86_64、sparc 和 ppc 系统中非 64 位到 32 位构建的交叉构建。CMAKE_SYSTEM_VERSION
:如果定义了tools.cmake.cmaketoolchain:system_version
配置,则使用该值,否则使用os.version
子设置(主机)(如果定义)。在 Apple 系统上,此os.version
将转换为相应的 Darwin 版本。CMAKE_SYSTEM_PROCESSOR
:如果定义了tools.cmake.cmaketoolchain:system_processor
配置,则使用该值,否则使用arch
设置(主机)(如果定义)
macOS 中对通用二进制文件的支持¶
警告
此功能是实验性的,可能会发生重大更改。有关更多信息,请参阅 Conan 稳定性 部分。
从 Conan 2.2.0 开始,初步支持使用 CMakeToolchain 在 macOS 上构建通用二进制文件。要在 Conan 中为通用二进制文件指定多个架构,请在定义设置中的架构时使用 | 分隔符。这种方法可以传递一个架构列表。例如,运行
conan create . --name=mylibrary --version=1.0 -s="arch=armv8|x86_64"
将为 *mylibrary* 创建一个包含 armv8
和 x86_64
两种架构的通用二进制文件,方法是在 *conan_toolchain.cmake* 文件中将 CMAKE_OSX_ARCHITECTURES
设置为 arm64;x86_64
。
警告
需要注意的是,此方法不适用于 CMake 以外的构建系统。
请注意,此功能主要有利于为发布目的构建最终的通用二进制文件。Conan 默认的每个架构管理一个二进制文件的行为通常提供更可靠、更省心的体验。用户应谨慎,不要过度依赖此功能进行更广泛的用例。
参考¶
- class CMakeToolchain(conanfile, generator=None)¶
- generate()¶
此方法将生成的M文件保存到 conanfile.generators_folder
conf¶
CMakeToolchain 受这些 [conf]
变量影响
tools.cmake.cmaketoolchain:toolchain_file 用户工具链文件,用于替换
conan_toolchain.cmake
。tools.cmake.cmaketoolchain:user_toolchain 从
conan_toolchain.cmake
文件中包含的用户工具链列表。tools.android:ndk_path
ANDROID_NDK_PATH
的值。tools.android:cmake_legacy_toolchain:
ANDROID_USE_LEGACY_TOOLCHAIN_FILE
的布尔值。它只会在conan_toolchain.cmake
中定义,如果给出了值。这在tools.android:ndk_path
配置中指定的 Android NDK 内的 CMake 工具链(版本r23c
及更高版本)中考虑。如果通过tools.build:cflags
或tools.build:cxxflags
定义了编译器标志,则将此设置为False
可能会很有用,以防止 Android 的旧版 CMake 工具链覆盖这些值。如果将此设置为False
,请确保您使用的是 CMake 3.21 或更高版本。tools.cmake.cmaketoolchain:system_name 在大多数情况下不是必需的,仅用于强制定义
CMAKE_SYSTEM_NAME
。tools.cmake.cmaketoolchain:system_version 在大多数情况下不是必需的,仅用于强制定义
CMAKE_SYSTEM_VERSION
。tools.cmake.cmaketoolchain:system_processor 在大多数情况下不是必需的,仅用于强制定义
CMAKE_SYSTEM_PROCESSOR
。tools.cmake.cmaketoolchain:enabled_blocks 定义哪些块已启用并丢弃其他块。
tools.cmake.cmaketoolchain:extra_variables:字典式 Python 对象,指定 CMake 变量名称和值。该值可以是普通字符串、数字或字典式 Python 对象,后者必须指定
value
(字符串/数字)、cache
(布尔值)、type
(CMake 缓存类型),并可选地指定docstring
(字符串:默认为变量名)和force
(布尔值)键。它可以覆盖 CMakeToolchain 定义的变量,用户自行承担风险。例如:
[conf]
tools.cmake.cmaketoolchain:extra_variables={'MY_CMAKE_VAR': 'MyValue'}
结果是
set(MY_CMAKE_VAR "MyValue")
这将在稍后注入,因此可以覆盖默认的 Conan 变量。
另一个高级用法
tools.cmake.cmaketoolchain:extra_variables={'MyIntegerVariable': 42, 'CMAKE_GENERATOR_INSTANCE': '${ENV}/buildTools/'}
tools.cmake.cmaketoolchain:extra_variables*={'CACHED_VAR': {'value': '/var/run', 'cache': True, 'type': 'PATH', 'docstring': 'test cache var', 'force': True}}
结果是
set(MyIntegerVariable 42)
set(CMAKE_GENERATOR_INSTANCE "${ENV}/buildTools/")
set(CACHED_VAR "/var/run" CACHE BOOL "test cache var" FORCE)
此块注入 $
,该符号将在稍后展开。它还定义了一个 PATH
类型的缓存变量。
提示
使用 配置数据操作符 *=
来 更新(而不是重新定义)配置文件或全局配置中已设置的 conf 变量。
tools.cmake.cmaketoolchain:toolset_arch:将在
conan_toolchain.cmake
文件的CMAKE_GENERATOR_TOOLSET
变量中添加,host=xxx
说明符。tools.cmake.cmaketoolchain:toolset_cuda:(实验性)将在
conan_toolchain.cmake
文件的CMAKE_GENERATOR_TOOLSET
变量中添加,cuda=xxx
说明符。tools.cmake.cmake_layout:build_folder_vars:设置、选项、
self.name
和self.version
以及常量const.uservalue
,它们将生成不同的构建文件夹和不同的 CMake 预设名称。tools.cmake.cmaketoolchain:presets_environment:设置为
'disabled'
以阻止向生成的 CMake 预设添加环境部分。tools.cmake.cmaketoolchain:user_presets:(实验性)允许为 CMakeUserPresets.json 文件设置自定义名称或子文件夹。空字符串将完全禁用文件生成。
tools.build:cxxflags 将追加到
CMAKE_CXX_FLAGS_INIT
的额外 C++ 标志列表。tools.build:cflags 将追加到
CMAKE_C_FLAGS_INIT
的额外纯 C 标志列表。tools.build:sharedlinkflags 将追加到
CMAKE_SHARED_LINKER_FLAGS_INIT
的额外链接器标志列表。tools.build:exelinkflags 将追加到
CMAKE_EXE_LINKER_FLAGS_INIT
的额外链接器标志列表。tools.build:defines 将被
add_definitions()
使用的预处理器定义列表。tools.apple:sdk_path
CMAKE_OSX_SYSROOT
的值。在一般情况下,它不需要,并将通过设置值传递给 CMake。tools.apple:enable_bitcode 布尔值,用于启用/禁用 Bitcode Apple Clang 标志,例如
CMAKE_XCODE_ATTRIBUTE_ENABLE_BITCODE
。tools.apple:enable_arc 布尔值,用于启用/禁用 ARC Apple Clang 标志,例如
CMAKE_XCODE_ATTRIBUTE_CLANG_ENABLE_OBJC_ARC
。tools.apple:enable_visibility 布尔值,用于启用/禁用 Visibility Apple Clang 标志,例如
CMAKE_XCODE_ATTRIBUTE_GCC_SYMBOLS_PRIVATE_EXTERN
。tools.build:sysroot 定义
CMAKE_SYSROOT
的值。tools.microsoft:winsdk_version 根据 CMake 策略
CMP0149
定义CMAKE_SYSTEM_VERSION
或CMAKE_GENERATOR_PLATFORM
。tools.build:compiler_executables 字典式 Python 对象,指定编译器作为键,编译器可执行文件路径作为值。这些键将按如下方式映射:
c
:将在 conan_toolchain.cmake 中设置CMAKE_C_COMPILER
。cpp
:将在 conan_toolchain.cmake 中设置CMAKE_CXX_COMPILER
。RC
:将在 conan_toolchain.cmake 中设置CMAKE_RC_COMPILER
。objc
:将在 conan_toolchain.cmake 中设置CMAKE_OBJC_COMPILER
。objcpp
:将在 conan_toolchain.cmake 中设置CMAKE_OBJCXX_COMPILER
。cuda
:将在 conan_toolchain.cmake 中设置CMAKE_CUDA_COMPILER
。fortran
:将在 conan_toolchain.cmake 中设置CMAKE_Fortran_COMPILER
。asm
:将在 conan_toolchain.cmake 中设置CMAKE_ASM_COMPILER
。hip
:将在 conan_toolchain.cmake 中设置CMAKE_HIP_COMPILER
。ispc
:将在 conan_toolchain.cmake 中设置CMAKE_ISPC_COMPILER
。