创建你的第一个 Conan 包

在前面的章节中，我们使用了 Conan 包（比如Zlib），首先使用conanfile.txt，然后使用conanfile.py。但是conanfile.py配方文件不仅用于使用其他包，还可以用于创建自己的包。在本节中，我们将解释如何使用conanfile.py配方创建一个简单的 Conan 包，以及如何使用 Conan 命令从源代码构建这些包。

重要

这是一个教程部分。鼓励您执行这些命令。对于这个具体的示例，您需要在路径中安装CMake。Conan 创建包并不严格需要它，您可以使用其他构建系统（如 VS、Meson、Autotools，甚至您自己的系统）来完成此操作，而无需依赖 CMake。

使用conan new命令创建一个“Hello World” C++ 库示例项目

$ conan new cmake_lib -d name=hello -d version=1.0

这将创建一个具有以下结构的 Conan 包项目。

.
├── CMakeLists.txt
├── conanfile.py
├── include
│   └── hello.h
├── src
│   └── hello.cpp
└── test_package
    ├── CMakeLists.txt
    ├── conanfile.py
    └── src
        └── example.cpp

生成的文件是

• conanfile.py：在根文件夹中，有一个conanfile.py，它是主要的配方文件，负责定义如何构建和使用包。

• CMakeLists.txt：一个简单的通用CMakeLists.txt，其中没有任何关于 Conan 的特定内容。

• src和include文件夹：包含简单 C++“hello”库的文件夹。

• test_package文件夹：包含一个示例应用程序，该应用程序将需要并链接到创建的包。它不是强制性的，但对于检查我们的包是否正确创建很有用。

让我们看看包配方conanfile.py

from conan import ConanFile
from conan.tools.cmake import CMakeToolchain, CMake, cmake_layout, CMakeDeps


class helloRecipe(ConanFile):
    name = "hello"
    version = "1.0"

    # Optional metadata
    license = "<Put the package license here>"
    author = "<Put your name here> <And your email here>"
    url = "<Package recipe repository url here, for issues about the package>"
    description = "<Description of hello package here>"
    topics = ("<Put some tag here>", "<here>", "<and here>")

    # Binary configuration
    settings = "os", "compiler", "build_type", "arch"
    options = {"shared": [True, False], "fPIC": [True, False]}
    default_options = {"shared": False, "fPIC": True}

    # Sources are located in the same place as this recipe, copy them to the recipe
    exports_sources = "CMakeLists.txt", "src/*", "include/*"

    def config_options(self):
        if self.settings.os == "Windows":
            del self.options.fPIC

    def layout(self):
        cmake_layout(self)

    def generate(self):
        deps = CMakeDeps(self)
        deps.generate()
        tc = CMakeToolchain(self)
        tc.generate()

    def build(self):
        cmake = CMake(self)
        cmake.configure()
        cmake.build()

    def package(self):
        cmake = CMake(self)
        cmake.install()

    def package_info(self):
        self.cpp_info.libs = ["hello"]

让我们简要解释一下配方的不同部分

首先，您可以看到定义的 Conan 包的名称和版本

• name：一个字符串，包含至少 2 个，最多 100 个小写字符，用于定义包名。它应该以字母数字或下划线开头，并且可以包含字母数字、下划线、+、.、- 字符。

• version：它是一个字符串，可以取任何值，与name属性具有相同的约束。如果版本遵循X.Y.Z-pre1+build2形式的语义版本控制，则该值可能用于通过版本范围而不是精确版本来要求此包。

然后您可以看到一些定义元数据的属性。这些是可选的，但建议使用，并定义诸如包的简短description、打包库的author、license、包存储库的url以及包相关的topics等内容。

之后，有一个与二进制配置相关的部分。此部分定义了包的有效设置和选项。正如我们在使用包部分中解释的那样

• settings是项目范围的配置，不能在配方中设置默认值。例如，操作系统、编译器或构建配置，这些配置将对多个 Conan 包通用

• options是包特定的配置，可以在配方中设置默认值，在本例中，我们有选择将包创建为共享库或静态库的选项，默认值为静态库。

之后，exports_sources属性设置为定义哪些源代码是 Conan 包的一部分。这些是您要打包的库的源代码。在本例中，是我们“hello”库的源代码。

然后，声明了几个方法

• config_options()方法（以及configure()方法）允许微调二进制配置模型，例如，在 Windows 中，没有fPIC选项，因此可以将其删除。

• layout()方法声明了我们期望找到源文件的位置以及构建过程中生成的文件的目标位置。例如，目标文件夹是为生成的可执行文件以及 Conan 生成器在generate()方法中创建的所有文件准备的。在本例中，由于我们的项目使用 CMake 作为构建系统，因此我们调用cmake_layout()。调用此函数将设置 CMake 项目的预期位置。

• generate()方法准备从源代码构建包。在本例中，它可以简化为一个属性generators = "CMakeToolchain"，但它被保留下来以展示这个重要的方法。在本例中，执行CMakeToolchaingenerate()方法将创建一个conan_toolchain.cmake文件，该文件将 Conan settings和options转换为 CMake 语法。添加CMakeDeps生成器是为了完整性，但除非向配方中添加requires，否则它不是严格必需的。

• build()方法使用CMake包装器来调用 CMake 命令，它是一个薄层，在本例中将管理传递-DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake参数。它将配置项目并从源代码构建它。

• package()方法将工件（头文件、库文件）从构建文件夹复制到最终的包文件夹。这可以通过简单的“复制”命令完成，但在本例中，它利用了已经存在的 CMake 安装功能（如果CMakeLists.txt没有实现它，则可以使用copy() 工具在package()方法中轻松编写等效的代码）。

• 最后，package_info()方法定义了使用者在使用此包时必须链接到“hello”库。其他信息（如包含路径或库路径）也可以定义。此信息用于由生成器（如CMakeDeps）创建的文件，供使用者使用。这是关于当前包的通用信息，无论他们使用什么构建系统，以及我们在build()方法中使用什么构建系统，使用者都可以使用。

test_package文件夹现在对于理解如何创建包并不重要。重要的部分是

• test_package文件夹与单元测试或集成测试不同。这些测试是“包”测试，并验证包是否正确创建以及包使用者是否能够链接到它并重用它。

• 它本身就是一个小型 Conan 项目，它包含其conanfile.py及其源代码（包括构建脚本），它依赖于正在创建的包，并构建和执行一个需要包中库的小型应用程序。

• 它不属于包。它只存在于源代码存储库中，而不存在于包中。

让我们使用当前默认配置从源代码构建包，然后让test_package文件夹测试包

$ conan create .

======== Exporting recipe to the cache ========
hello/1.0: Exporting package recipe
...
hello/1.0: Exported: hello/1.0#dcbfe21e5250264b26595d151796be70 (2024-03-04 17:52:39 UTC)

======== Installing packages ========
-------- Installing package hello/1.0 (1 of 1) --------
hello/1.0: Building from source
hello/1.0: Calling build()
...
hello/1.0: Package '9bdee485ef71c14ac5f8a657202632bdb8b4482b' built

======== Testing the package: Building ========
...
[ 50%] Building CXX object CMakeFiles/example.dir/src/example.cpp.o
[100%] Linking CXX executable example
[100%] Built target example

======== Testing the package: Executing test ========
hello/1.0 (test package): Running test()
hello/1.0 (test package): RUN: ./example
hello/1.0: Hello World Release!
  hello/1.0: __aarch64__ defined
  hello/1.0: __cplusplus201703
  hello/1.0: __GNUC__4
  hello/1.0: __GNUC_MINOR__2
  hello/1.0: __clang_major__15
  hello/1.0: __apple_build_version__15000309
...

如果显示“Hello world Release！”，则表示成功。这就是发生的事情

• conanfile.py以及src文件夹的内容已被复制（在 Conan 中称为导出）到本地 Conan 缓存。

• 从源代码开始构建hello/1.0包，调用generate()、build()和package()方法。这将在 Conan 缓存中创建二进制包。

• 然后，Conan 移动到test_package文件夹并执行conan install + conan build + test()方法，以检查包是否正确创建。

我们现在可以验证配方和包二进制文件是否在缓存中

$ conan list hello
Local Cache
  hello
    hello/1.0

conan create命令接收与conan install相同的参数，因此您可以向它传递相同的设置和选项。如果我们执行以下行，我们将为 Debug 配置创建新的包二进制文件或将 hello 库构建为共享库

$ conan create . -s build_type=Debug
...
hello/1.0: Hello World Debug!

$ conan create . -o hello/1.0:shared=True
...
hello/1.0: Hello World Release!

这些新的包二进制文件也将存储在 Conan 缓存中，准备供这台计算机上的任何项目使用。我们可以使用以下命令查看它们

# list all the binaries built for the hello/1.0 package in the cache
$ conan list "hello/1.0:*"
Local Cache
  hello
    hello/1.0
      revisions
        dcbfe21e5250264b26595d151796be70 (2024-05-10 09:40:15 UTC)
          packages
            2505f7ebb5a4cca156b2d6b8534f415a4a48b5c9
              info
                settings
                  arch: armv8
                  build_type: Release
                  compiler: apple-clang
                  compiler.cppstd: gnu17
                  compiler.libcxx: libc++
                  compiler.version: 15
                  os: Macos
                options
                  shared: True
            39f48664f195e0847f59889d8a4cdfc6bca84bf1
              info
                settings
                  arch: armv8
                  build_type: Release
                  compiler: apple-clang
                  compiler.cppstd: gnu17
                  compiler.libcxx: libc++
                  compiler.version: 15
                  os: Macos
                options
                  fPIC: True
                  shared: False
            814ddaac84bc84f3595aa076660133b88e49fb11
              info
                settings
                  arch: armv8
                  build_type: Debug
                  compiler: apple-clang
                  compiler.cppstd: gnu17
                  compiler.libcxx: libc++
                  compiler.version: 15
                  os: Macos
                options
                  fPIC: True
                  shared: False

现在我们已经创建了一个简单的 Conan 包，我们将更详细地解释 Conanfile 的每个方法。您将学习如何修改这些方法以实现诸如从外部存储库检索源代码、向我们的包添加依赖项、自定义我们的工具链等等。

关于 Conan 缓存的说明

当您执行conan create命令时，您的包的构建不会发生在您的本地文件夹中，而是在Conan 缓存内的其他文件夹中。此缓存位于用户主文件夹下的.conan2文件夹中。Conan 将使用~/.conan2文件夹来存储构建的包以及不同的配置文件。您已经使用conan list命令列出了存储在本地缓存中的配方和二进制文件。

一个重要说明：Conan 缓存对 Conan 客户端是私有的 - 修改、添加、删除或更改 Conan 缓存内的文件是未定义的行为，可能会导致损坏。

另请参阅

• 使用 Visual Studio/MSBuild 创建你的第一个 Conan 包.

• 使用 Meson 创建你的第一个 Conan 包.

• 使用 Autotools 创建你的第一个 Conan 包（仅限 Linux）.

• CMake 内置集成参考

  .

• Conan create 命令参考 和 Conan list 命令参考。