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()
CMakeLists.txt
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_PATHCMAKE_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) 包含此文件,并提供一个名为 CONANDEPS_LEGACY 的 CMake 变量,允许链接所有直接和传递依赖项,而无需显式列举它们,例如:target_link_libraries(app ${CONANDEPS_LEGACY})。这为 Conan 1.X 用户升级到 Conan 2 提供了便利,而无需改变其整体开发流程,但除此之外不建议使用,并且使用 CMake 规范流程,即显式使用 find_package()target_link_libraries(... pkg1::pkg1 pkg2::pkg2) 和目标,才是正确的方法。

自定义

您可以调整所创建的 CMakeDeps 对象中的某些属性以更改默认行为

配置

允许除了标准 Release、Debug 等之外,定义自定义的用户 CMake 配置。

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-requireregular 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 相关的问题。您可能知道,依赖项的配方可以声明一个包含一个或多个 .cmake 文件的 cppinfo.build_modules 条目。当 cmake find_package() 函数找到该依赖项时,Conan 将自动包含这些文件。

默认情况下,Conan 将只包含来自 host 上下文(常规依赖项)的构建模块,以避免冲突,但您可以更改默认行为。

使用 build_context_build_modules 属性指定要包含 tool_requiresbuild_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() 中指定组件时添加检查,请使用此属性。例如,如果我们正在使用一个声明了多个组件的 Conan 包,如 Boost。如果我们将属性设置为 True,则消费者的 find_package() 调用将检查所需的组件是否存在,否则会引发错误。您可以在 generate() 方法中设置此属性

requires = "boost/1.81.0"

...

def generate(self):
    deps = CMakeDeps(self)
    deps.check_components_exist = True
    deps.generate()

然后,当使用 Boost 时,find_package() 将因 fakecomp 不存在而引发错误

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 配方设置的 property 值。这可以用于 cmake_file_namecmake_target_namecmake_find_modecmake_module_file_namecmake_module_target_namecmake_additional_variables_prefixescmake_config_version_compatsystem_package_versioncmake_build_modulesnosonamecmake_target_aliases

参数:
  • dep – 要设置 属性 的依赖项名称。对于组件,使用语法:dep_name::component_name

  • prop属性 的名称。

  • value – 属性的值。使用 None 来使上游配方设置的任何值无效。

  • build_context – 如果您想为属于构建上下文的依赖项设置属性(默认为 False),则设置为 True

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 生成器中,需要根据 CPS 实践正确指定 cpp_info 中的库详细信息。

  • 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 配方设置的属性值。这可以对上面列出的每个属性进行操作。

想象一下我们有一个依赖于 zlib/1.3.1compressor/1.0 包。zlib 配方定义了一些属性

Zlib conanfile.py
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")
        ...

此配方定义了几个属性。例如,cmake_find_mode 属性设置为 both。这意味着为 Zlib 生成了模块和配置文件。也许我们需要更改此行为,只生成配置文件。您可以在 compressor 配方中使用 CMakeDeps.set_property() 方法来完成此操作

compressor conanfile.py
class Compressor(ConanFile):
    name = "compressor"

    requires = "zlib/1.3.1"
    ...

    def generate(self):
        deps = CMakeDeps(self)
        deps.set_property("zlib", "cmake_find_mode", "config")
        deps.generate()
        ...

您还可以使用 set_property() 方法来使上游配方设置的属性值无效,并使用 Conan 默认分配的值。为此,将属性值设置为 None,如下所示

compressor conanfile.py
class Compressor(ConanFile):
    name = "compressor"

    requires = "zlib/1.3.1"
    ...

    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()
    ...

禁用 CMakeDeps 以用于已安装的 CMake 配置文件

一些项目可能希望对下游消费者禁用 CMakeDeps 生成器。这可以通过将 cmake_find_mode 设置为 none 来实现。如果项目希望提供自己的配置目标,则应将其附加到 cpp_infobuildirs 属性中。

此方法旨在与使用 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