CMakeToolchain:在包中使用 xxx-config.cmake 文件

在一般情况下,Conan 依赖于 package_info() 抽象,以允许使用任何构建系统构建的包能被使用任何其他构建系统构建的其他包使用。在 CMake 的情况下,Conan 依赖于 CMakeDeps 生成器为每个依赖项生成 xxxx-config.cmake 文件,即使这些依赖项没有生成文件或根本没有使用 CMake 构建。

ConanCenter 用户使用这种抽象,不打包 xxx-config.cmake 文件,而是使用 package_info() 中的信息。这对于提供尽可能与构建系统无关的包,并公平对待不同的构建系统、供应商和用户来说非常重要。例如,许多 Conan 用户很高兴地使用原生 MSBuild (VS) 项目,完全不使用 CMake。如果 ConanCenter 包只能使用包内的 config.cmake 文件构建,那这将是不可能的。

但 ConanCenter 这样做,并不意味着这不可能或不是强制性的。完全可以使用包内的 xxx-config.cmake 文件,放弃使用 CMakeDeps 生成器。

您可以在 GitHub 上的 examples2 仓库 中找到重现此示例的源代码。

$ git clone https://github.com/conan-io/examples2.git
$ cd examples2/examples/tools/cmake/pkg_config_files

如果我们看一下 conanfile.py

class pkgRecipe(ConanFile):
    name = "pkg"
    version = "0.1"
    ...

    def package_info(self):
        # No information provided, only the in-package .cmake is used here
        # Other build systems or CMake via CMakeDeps will fail
        self.cpp_info.builddirs = ["pkg/cmake"]
        self.cpp_info.set_property("cmake_find_mode", "none")

这是一个非常典型的配方,主要区别在于 package_info() 方法。有三点需要注意:

  • 它没有定义诸如 self.cpp_info.libs = ["mypkg"] 的字段。Conan 不会将此信息传播给消费者,此信息将只存在于包内的 xxx-config.cmake 文件中。

  • 仅为了防止有些用户仍在使用 CMakeDeps,它通过 set_property("cmake_find_mode", "none") 禁用了客户端生成 xxx-config.cmake 文件。

  • 它定义了该文件夹内将包含构建脚本(例如 xxx-config.cmake 包),供消费者查找。

因此,定义包细节的责任已转移到包含以下内容的 CMakeLists.txt 文件中:

add_library(mylib src/pkg.cpp)  # Use a different name than the package, to make sure

set_target_properties(mylib PROPERTIES PUBLIC_HEADER "include/pkg.h")
target_include_directories(mylib PUBLIC
        $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
    )

# Use non default mypkgConfig name
install(TARGETS mylib EXPORT mypkgConfig)
export(TARGETS mylib
    NAMESPACE mypkg::  # to simulate a different name and see it works
    FILE "${CMAKE_CURRENT_BINARY_DIR}/mypkgConfig.cmake"
)
install(EXPORT mypkgConfig
    DESTINATION "${CMAKE_INSTALL_PREFIX}/pkg/cmake"
    NAMESPACE mypkg::
)

有了这些信息,当执行 conan create

  • build() 方法将构建包

  • package() 方法将调用 cmake install,这将创建 mypkgConfig.cmake 文件

  • 它将在包文件夹 pkg/cmake/mypkgConfig.cmake 文件中创建。

  • 它将包含足够的头文件信息,并创建一个 mypkg::mylib 目标。

请注意,配置文件名、命名空间和目标的详细信息 Conan 也未知,因此这也是消费者构建脚本应该知道的内容。

这足以拥有一个包含内部 mypkgConfig.cmake 文件并可供消费者使用的包。在此示例代码中,消费者仅是 test_package/conanfile.py,但完全相同的方法也适用于任何任意消费者。

消费者 conanfile.py 完全不需要使用 CMakeDeps,只需要 generators = "CMakeToolchain"。请注意,CMakeToolchain 生成器仍然是必需的,因为 mypkgConfig.cmake 需要在 Conan 缓存中找到。CMakeToolchain 生成的 conan_toolchain.cmake 文件包含这些已定义的路径。

消费者 CMakeLists.txt 将是标准配置。

find_package(mypkg CONFIG REQUIRED)

add_executable(example src/example.cpp)
target_link_libraries(example mypkg::mylib)

您可以使用以下方式验证其是否有效:

$ conan create .

======== Testing the package: Executing test ========
pkg/0.1 (test package): Running test()
pkg/0.1 (test package): RUN: Release\example
pkg/0.1: Hello World Release!
pkg/0.1: _M_X64 defined
pkg/0.1: MSVC runtime: MultiThreadedDLL
pkg/0.1: _MSC_VER1939
pkg/0.1: _MSVC_LANG201402
pkg/0.1: __cplusplus199711
pkg/0.1 test_package

重要注意事项

所提出的方法有一个限制,它不适用于多配置 IDE。实施此方法将不允许开发人员直接在 Visual Studio 等 IDE 中从 Release 切换到 Debug,反之亦然,并且需要执行 conan install 才能更改。对于单配置设置而言,这根本不是问题,但对于 VS 开发人员来说可能会有些不便。团队正在开发 VS 插件,这可能会有助于缓解此问题。原因是 CMake 的限制,find_package() 只能找到一种配置,并且由于此处放弃了 CMakeDeps,Conan 无法做任何事情来避免此限制。

重要的是要知道,正确管理对其他依赖项的传递性也是包作者和包的 CMakeLists.txt 的责任,在某些情况下这并非易事。如果操作不当,包内的 xxx-config.cmake 文件可能会在其他地方(例如在系统中)找到其传递依赖项,而不是在传递的 Conan 包依赖项中,这存在风险。

最后,请记住,这些包将无法被 CMake 以外的其他构建系统使用。