CMakeDeps¶
CMakeDeps
生成器为每个依赖项生成必要的文件,以便能够使用 CMake 的 find_package()
函数来定位依赖项。它可以这样使用:
from conan import ConanFile
class App(ConanFile):
settings = "os", "arch", "compiler", "build_type"
requires = "hello/0.1"
generators = "CMakeDeps"
允许自定义配置的完整实例化可以在 generate()
方法中完成:
from conan import ConanFile
from conan.tools.cmake import CMakeDeps
class App(ConanFile):
settings = "os", "arch", "compiler", "build_type"
requires = "hello/0.1"
def generate(self):
cmake = CMakeDeps(self)
cmake.generate()
cmake_minimum_required(VERSION 3.15)
project(compressor C)
find_package(hello REQUIRED)
add_executable(${PROJECT_NAME} src/main.c)
target_link_libraries(${PROJECT_NAME} hello::hello)
默认情况下,对于 hello
依赖项,您需要使用 find_package(hello)
并链接到目标 hello::hello
。请查阅 影响 CMakeDeps 的属性,例如 cmake_target_name
,以在依赖项及其组件的 conanfile.py 中自定义文件和目标名称。
注意
CMakeDeps
旨在与 CMakeToolchain
生成器一起运行。它将 CMAKE_PREFIX_PATH
和 CMAKE_MODULE_PATH
设置到正确的文件夹(conanfile.generators_folder
),以便 CMake 可以定位生成的配置/模块文件。
生成的文件¶
XXX-config.cmake:默认情况下,CMakeDeps 生成器将创建声明依赖项及其组件(如果已声明)目标的配置文件。
FindXXX.cmake:仅当依赖项设置了属性
cmake_find_mode
为“module”或“both”时。参见依赖项中设置的 影响 CMakeDeps 的属性。其他必要的 *.cmake 文件:例如版本、标志和目录数据或配置。
请注意,它还会生成一个 conandeps_legacy.cmake 文件。此文件提供了与 Conan 1 cmake
生成器类似的行为,允许通过 include(${CMAKE_BINARY_DIR}/generators/conandeps_legacy.cmake)
包含此文件,并提供一个单独的 CMake 变量 CONANDEPS_LEGACY
,允许链接所有直接和传递依赖项,而无需明确列举它们,例如:target_link_libraries(app ${CONANDEPS_LEGACY})
。这是为 Conan 1.X 用户提供的便利,以便在不改变其整体开发流程的情况下升级到 Conan 2,但除此以外不建议使用,而正确的方法是使用 CMake 规范流程,明确使用 find_package()
和 target_link_libraries(... pkg1::pkg1 pkg2::pkg2)
及其目标。
自定义¶
您可以调整创建的 CMakeDeps
对象中的某些属性以更改默认行为
配置¶
允许定义自定义用户 CMake 配置,除了标准的 Release、Debug 等配置。
def generate(self):
deps = CMakeDeps(self)
# By default, ``deps.configuration`` will be ``self.settings.build_type``
if self.options["hello"].shared:
# Assuming the current project ``CMakeLists.txt`` defines the ReleasedShared configuration.
deps.configuration = "ReleaseShared"
deps.generate()
CMakeDeps
是一个多配置生成器,它可以正确创建 Release/Debug 配置的文件,以便 IDE(如 Visual Studio)同时使用。在单配置环境中,需要定义一个配置,该配置必须通过命令行中的 cmake ... -DCMAKE_BUILD_TYPE=<build-type>
参数提供(Conan 会在必要时在 CMake.configure()
辅助函数中自动完成)。
build_context_activated¶
当您有一个构建依赖(build-require)时,默认情况下,不会生成配置文件(xxx-config.cmake)文件。但您可以使用 build_context_activated 属性来激活它
tool_requires = ["my_tool/0.0.1"]
def generate(self):
cmake = CMakeDeps(self)
# generate the config files for the tool require
cmake.build_context_activated = ["my_tool"]
cmake.generate()
build_context_suffix¶
当您将同一个包既作为构建依赖(build-require)又作为常规依赖(regular require)时,它将导致生成器冲突,因为配置文件的文件名会冲突,目标名称、变量名称等也会冲突。
例如,这是一种常见情况,某些依赖项(capnproto、protobuf…)包含一个用于在构建时生成源代码的工具(因此它是一个 build_require),但也提供一个库用于链接到最终应用程序,因此您也需要一个常规依赖(regular require)。解决此冲突尤其重要,因为在交叉构建时,工具(将在构建机器上运行)属于与库不同的二进制包,而库将在主机上“运行”。
您可以使用 build_context_suffix 属性为依赖项指定一个后缀,这样构建上下文(工具依赖)中依赖项的文件/目标/变量将被重命名
tool_requires = ["my_tool/0.0.1"]
requires = ["my_tool/0.0.1"]
def generate(self):
cmake = CMakeDeps(self)
# generate the config files for the tool require
cmake.build_context_activated = ["my_tool"]
# disambiguate the files, targets, etc
cmake.build_context_suffix = {"my_tool": "_BUILD"}
cmake.generate()
build_context_build_modules¶
另外还有一个与 build_modules 相关的问题。您可能知道,依赖项的 recipe 可以声明一个 cppinfo.build_modules 条目,其中包含一个或多个 .cmake 文件。当 CMake 的 find_package()
函数找到该依赖项时,Conan 会自动包含这些文件。
默认情况下,Conan 只会包含 host
上下文(常规依赖)中的构建模块,以避免冲突,但您可以更改此默认行为。
使用 build_context_build_modules 属性来指定需要包含来自 tool_requires 的 build_modules 的依赖项名称
tool_requires = ["my_tool/0.0.1"]
def generate(self):
cmake = CMakeDeps(self)
# generate the config files for the tool require
cmake.build_context_activated = ["my_tool"]
# Choose the build modules from "build" context
cmake.build_context_build_modules = ["my_tool"]
cmake.generate()
check_components_exist¶
警告
check_components_exist
属性是实验性的,可能会发生变化。
此属性默认为 False
。如果您希望在消费者 find_package()
中指定组件时添加检查,请使用此属性。例如,如果我们正在使用一个像 Boost 这样声明了多个组件的 Conan 包。如果我们将此属性设置为 True
,则消费者的 find_package()
调用将检查所需的组件是否存在,否则会引发错误。您可以在 generate()
方法中设置此属性
requires = "boost/1.81.0"
...
def generate(self):
deps = CMakeDeps(self)
deps.check_components_exist = True
deps.generate()
然后,在使用 Boost 时,如果 fakecomp 不存在,find_package()
将引发错误
cmake_minimum_required(VERSION 3.15)
...
find_package(Boost COMPONENTS random regex fakecomp REQUIRED)
...
参考¶
- class CMakeDeps(conanfile)¶
- generate()¶
此方法会将生成的文件保存到 conanfile.generators_folder
- set_property(dep, prop, value, build_context=False)¶
使用此方法,您可以从消费者端覆盖 Conan recipe 设置的 属性 值。这可以用于 cmake_file_name、cmake_target_name、cmake_find_mode、cmake_module_file_name、cmake_module_target_name、cmake_additional_variables_prefixes、cmake_config_version_compat、system_package_version、cmake_build_modules、nosoname 和 cmake_target_aliases。
- get_cmake_package_name(dep, module_mode=None)¶
获取 find_package(XXX) 文件的名称
- get_find_mode(dep)¶
- 参数:
dep – 依赖项
- 返回:
“none”或“config”或“module”或“both”或未设置时为“config”
属性¶
以下属性会影响 CMakeDeps 生成器
cmake_file_name:为当前包生成的配置文件将遵循
<VALUE>-config.cmake
模式,因此要查找包,您需要编写find_package(<VALUE>)
。cmake_target_name:要消费的目标名称。
cmake_target_aliases:Conan 将为现有目标创建的别名列表。
cmake_find_mode:默认为
config
。可能的值有:config
:CMakeDeps 生成器将为依赖项创建配置脚本。module
:将为依赖项创建模块配置 (FindXXX.cmake) 脚本。both
:将同时生成配置和模块。none
:不生成任何文件。例如,它可以用于创建系统包装包,以便消费者在 CMake 安装配置路径中而不是在 Conan 生成的路径中找到配置文件(因为它已被跳过)。
cmake_module_file_name:与 cmake_file_name 相同,但在使用
cmake_find_mode=module/both
生成模块时使用。如果未指定,将默认为 cmake_file_name。cmake_module_target_name:与 cmake_target_name 相同,但在使用
cmake_find_mode=module/both
生成模块时使用。如果未指定,将默认为 cmake_target_name。cmake_build_modules:
.cmake
文件列表(相对于根包文件夹的路径),当消费者运行find_package()
时会自动包含。此属性不能在组件中设置,只能在根self.cpp_info
中设置。cmake_set_interface_link_directories:(在 2.14 中已废弃)。它很久以前用于
#pragma comment(lib, "foo")
,但对于CMakeDeps
生成器而言已不再必要。在新的CMakeConfigDeps
生成器中,需要正确指定cpp_info
中的库详细信息,与 CPS 实践保持一致。nosoname:布尔值,仅应由定义为
SHARED
且表示未带soname
标志选项构建的库的依赖项使用。cmake_config_version_compat:默认为
SameMajorVersion
,可取值为"AnyNewerVersion", "SameMajorVersion", "SameMinorVersion", "ExactVersion"
。它将在生成的<PackageName>ConfigVersion.cmake
文件中使用该策略system_package_version:用于生成
<PackageName>ConfigVersion.cmake
文件的包版本。在创建系统包或其他包装包时可能有用,其中 Conan 包版本与最终引用的包版本不同,以保持与find_package(<PackageName> <Version>)
调用的兼容性。cmake_additional_variables_prefixes:在配置文件中创建 CMake 变量时使用的前缀列表。默认情况下,这些变量以前缀
file_name
创建,但设置此属性将除默认file_name
外,还会创建带有指定前缀的其他变量。
示例
def package_info(self):
...
# MyFileName-config.cmake
self.cpp_info.set_property("cmake_file_name", "MyFileName")
# Names for targets are absolute, Conan won't add any namespace to the target names automatically
self.cpp_info.set_property("cmake_target_name", "Foo::Foo")
# Automatically include the lib/mypkg.cmake file when calling find_package()
# This property cannot be set in a component.
self.cpp_info.set_property("cmake_build_modules", [os.path.join("lib", "mypkg.cmake")])
# Create a new target "MyFooAlias" that is an alias to the "Foo::Foo" target
self.cpp_info.set_property("cmake_target_aliases", ["MyFooAlias"])
self.cpp_info.components["mycomponent"].set_property("cmake_target_name", "Foo::Var")
# Create a new target "VarComponent" that is an alias to the "Foo::Var" component target
self.cpp_info.components["mycomponent"].set_property("cmake_target_aliases", ["VarComponent"])
# Skip this package when generating the files for the whole dependency tree in the consumer
# note: it will make useless the previous adjustements.
# self.cpp_info.set_property("cmake_find_mode", "none")
# Generate both MyFileNameConfig.cmake and FindMyFileName.cmake
self.cpp_info.set_property("cmake_find_mode", "both")
使用 CMakeDeps.set_property() 从消费者端覆盖属性¶
使用 CMakeDeps.set_property()
方法,您可以从消费者端覆盖 Conan recipe 设置的属性值。这可以用于上面列出的所有属性。
假设我们有一个依赖于 zlib/1.2.11 的 compressor/1.0 包。zlib recipe 定义了一些属性
class ZlibConan(ConanFile):
name = "zlib"
...
def package_info(self):
self.cpp_info.set_property("cmake_find_mode", "both")
self.cpp_info.set_property("cmake_file_name", "ZLIB")
self.cpp_info.set_property("cmake_target_name", "ZLIB::ZLIB")
...
此 recipe 定义了几个属性。例如,cmake_find_mode
属性设置为 both
。这意味着会为 Zlib 生成模块和配置文件。也许我们需要改变这种行为,只生成配置文件。您可以在 compressor recipe 中使用 CMakeDeps.set_property()
方法来实现
class Compressor(ConanFile):
name = "compressor"
requires = "zlib/1.2.11"
...
def generate(self):
deps = CMakeDeps(self)
deps.set_property("zlib", "cmake_find_mode", "config")
deps.generate()
...
您还可以使用 set_property()
方法来使上游 recipe 设置的属性值无效,并使用 Conan 默认分配的值。为此,将属性的值设置为 None
,如下所示
class Compressor(ConanFile):
name = "compressor"
requires = "zlib/1.2.11"
...
def generate(self):
deps = CMakeDeps(self)
deps.set_property("zlib", "cmake_target_name", None)
deps.generate()
...
完成此操作后,Zlib 库的生成目标名称将是 zlib::zlib
而不是 ZLIB::ZLIB
此外,CMakeDeps.set_property() 也可以用于包含组件的包。在这种情况下,您需要提供包名称及其组件,并用双冒号(::)分隔。示例如下
def generate(self):
deps = CMakeDeps(self)
deps.set_property("pkg::component", "cmake_target_name", <new_component_target_name>)
deps.generate()
...
为已安装的 CMake 配置文件禁用 CMakeDeps¶
有些项目可能希望为下游消费者禁用 CMakeDeps
生成器。这可以通过将 cmake_find_mode
设置为 none
来实现。如果项目希望提供自己的配置目标,则应将其附加到 cpp_info
的 buildirs
属性中。
此方法旨在与使用 CMakeToolchain
生成器的下游消费者一起工作,该生成器将填充 builddirs
属性。
示例
def package(self):
...
cmake.install()
def package_info(self):
self.cpp_info.set_property("cmake_find_mode", "none") # Do NOT generate any files
self.cpp_info.builddirs.append(os.path.join("lib", "cmake", "foo"))
从项目配置映射到导入目标的配置¶
如前所述,CMakeDeps
支持多配置环境(Debug、Release 等)。这是通过在安装依赖项时根据 build_type
设置填充导入目标的属性来实现的。但是,当消费者项目使用单配置 CMake 生成器进行配置时,需要定义 CMAKE_BUILD_TYPE
,其值必须与已安装依赖项的值匹配。
如果消费者 CMake 项目配置的构建类型与依赖项不同,则需要通过设置 CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>
CMake 变量来告诉 CMake 如何将当前项目的配置映射到导入的目标。
cd build-coverage/
conan install .. -s build_type=Debug
cmake .. -DCMAKE_BUILD_TYPE=Coverage -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_MAP_IMPORTED_CONFIG_COVERAGE=Debug