理解使用 conanfile.py 与 conanfile.txt 的灵活性¶
在之前的示例中,我们在 conanfile.txt 文件中声明了我们的依赖项(Zlib 和 CMake)。 让我们看一下该文件
[requires]
zlib/1.2.11
[tool_requires]
cmake/3.22.6
[generators]
CMakeDeps
CMakeToolchain
对于简单的用例,使用 conanfile.txt 通过 Conan 构建项目已经足够了,但是如果你需要更高的灵活性,你应该使用 conanfile.py 文件,你可以在其中使用 Python 代码来执行诸如动态添加需求、根据其他选项更改选项或为你的需求设置选项等操作。 让我们看一个示例,了解如何迁移到 conanfile.py 并使用其中的一些功能。
请首先克隆源代码以重新创建此项目。 你可以在 GitHub 的 examples2 仓库中找到它们
$ git clone https://github.com/conan-io/examples2.git
$ cd examples2/tutorial/consuming_packages/conanfile_py
检查文件夹的内容,并注意内容与之前的示例相同,但使用 conanfile.py 而不是 conanfile.txt。
.
├── CMakeLists.txt
├── conanfile.py
└── src
└── main.c
请记住,在之前的示例中,conanfile.txt 具有以下信息
[requires]
zlib/1.2.11
[tool_requires]
cmake/3.22.6
[generators]
CMakeDeps
CMakeToolchain
我们将把相同的信息转换为 conanfile.py。 此文件通常被称为 “Conan 配方”。 它可以用于使用软件包(如本例所示),也可以用于创建软件包。 对于我们当前的情况,它将定义我们的需求(库和构建工具)以及修改选项和设置我们希望如何使用这些软件包的逻辑。 如果使用此文件创建软件包,它可以定义(除其他外)如何下载软件包的源代码、如何从这些源代码构建二进制文件、如何打包二进制文件以及有关未来使用者如何使用软件包的信息。 我们将在后面的 创建软件包 部分解释如何使用 Conan 配方来创建软件包。
conanfile.txt 的等效 Conan 配方可能如下所示
from conan import ConanFile
class CompressorRecipe(ConanFile):
settings = "os", "compiler", "build_type", "arch"
generators = "CMakeToolchain", "CMakeDeps"
def requirements(self):
self.requires("zlib/1.2.11")
def build_requirements(self):
self.tool_requires("cmake/3.22.6")
要创建 Conan 配方,我们声明了一个新的类,该类继承自 ConanFile
类。 此类具有不同的类属性和方法
settings 类属性定义了项目范围的变量,例如编译器、其版本或操作系统本身,这些变量可能会在我们构建项目时发生变化。 这与 Conan 如何管理二进制兼容性有关,因为这些值将影响 Conan 软件包的 package ID 值。 我们将在稍后解释 Conan 如何使用此值来管理二进制兼容性。
generators 类属性指定了当我们调用 conan install 命令时将运行哪些 Conan 生成器。 在本例中,我们像在 conanfile.txt 中一样添加了 CMakeToolchain 和 CMakeDeps。
在 requirements() 方法中,我们使用
self.requires()
方法来声明 zlib/1.2.11 依赖项。在 build_requirements() 方法中,我们使用
self.tool_requires()
方法来声明 cmake/3.22.6 依赖项。
注意
并非必须将工具的依赖项添加到 build_requirements()
中,因为理论上此方法中的所有内容都可以在 requirements()
方法中完成。 但是,build_requirements()
提供了一个专门的位置来定义 tool_requires
和 test_requires
,这有助于保持结构的组织性和清晰度。 有关更多信息,请查看 requirements() 和 build_requirements() 文档。
你可以检查运行与之前示例中相同的命令将导致与之前相同的结果。
$ conan install . --output-folder=build --build=missing
$ cd build
$ conanbuild.bat
# assuming Visual Studio 15 2017 is your VS version and that it matches your default profile
$ cmake .. -G "Visual Studio 15 2017" -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake
$ cmake --build . --config Release
...
Building with CMake version: 3.22.6
...
[100%] Built target compressor
$ Release\compressor.exe
Uncompressed size is: 233
Compressed size is: 147
ZLIB VERSION: 1.2.11
$ deactivate_conanbuild.bat
$ conan install . --output-folder build --build=missing
$ cd build
$ source conanbuild.sh
Capturing current environment in deactivate_conanbuildenv-release-x86_64.sh
Configuring environment variables
$ cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
$ cmake --build .
...
Building with CMake version: 3.22.6
...
[100%] Built target compressor
$ ./compressor
Uncompressed size is: 233
Compressed size is: 147
ZLIB VERSION: 1.2.11
$ source deactivate_conanbuild.sh
到目前为止,我们已经实现了与使用 conanfile.txt 相同的功能。 让我们看看如何利用 conanfile.py 的功能来定义我们想要遵循的项目结构,并使用 Conan 设置和选项添加一些逻辑。
使用 layout() 方法¶
在之前的示例中,每次执行 conan install 命令时,我们都必须使用 –output-folder 参数来定义我们想要在哪里创建 Conan 生成的文件。 有一种更简洁的方法来决定我们希望 Conan 为构建系统生成文件的位置,这将允许我们决定,例如,我们是否希望根据我们使用的 CMake 生成器类型使用不同的输出文件夹。 你可以直接在 conanfile.py 中的 layout() 方法中定义此项,并使其在每个平台上工作,而无需添加更多更改。
import os
from conan import ConanFile
class CompressorRecipe(ConanFile):
settings = "os", "compiler", "build_type", "arch"
generators = "CMakeToolchain", "CMakeDeps"
def requirements(self):
self.requires("zlib/1.2.11")
if self.settings.os == "Windows":
self.requires("base64/0.4.0")
def build_requirements(self):
if self.settings.os != "Windows":
self.tool_requires("cmake/3.22.6")
def layout(self):
# We make the assumption that if the compiler is msvc the
# CMake generator is multi-config
multi = True if self.settings.get_safe("compiler") == "msvc" else False
if multi:
self.folders.generators = os.path.join("build", "generators")
self.folders.build = "build"
else:
self.folders.generators = os.path.join("build", str(self.settings.build_type), "generators")
self.folders.build = os.path.join("build", str(self.settings.build_type))
正如你所看到的,我们在 layout() 方法中定义了 self.folders.generators 属性。 这是所有 Conan 生成的辅助文件(CMake 工具链和 cmake 依赖项文件)将放置的文件夹。
请注意,如果它是多配置生成器(例如 Visual Studio),则文件夹的定义是不同的;或者如果是单配置生成器(例如 Unix Makefiles)。 在第一种情况下,文件夹与构建类型无关,并且构建系统将在该文件夹内管理不同的构建类型。 但是像 Unix Makefiles 这样的单配置生成器必须为每个配置使用不同的文件夹(作为不同的 build_type Release/Debug)。 在这种情况下,我们添加了一个简单的逻辑来考虑编译器名称是否为 msvc 来判断是否为多配置。
检查运行与之前示例中相同的命令,但不带 –output-folder 参数,将导致与之前相同的结果
$ conan install . --build=missing
$ cd build
$ generators\conanbuild.bat
# assuming Visual Studio 15 2017 is your VS version and that it matches your default profile
$ cmake .. -G "Visual Studio 15 2017" -DCMAKE_TOOLCHAIN_FILE=generators\conan_toolchain.cmake
$ cmake --build . --config Release
...
Building with CMake version: 3.22.6
...
[100%] Built target compressor
$ Release\compressor.exe
Uncompressed size is: 233
Compressed size is: 147
ZLIB VERSION: 1.2.11
$ generators\deactivate_conanbuild.bat
$ conan install . --build=missing
$ cd build/Release
$ source ./generators/conanbuild.sh
Capturing current environment in deactivate_conanbuildenv-release-x86_64.sh
Configuring environment variables
$ cmake ../.. -DCMAKE_TOOLCHAIN_FILE=generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
$ cmake --build .
...
Building with CMake version: 3.22.6
...
[100%] Built target compressor
$ ./compressor
Uncompressed size is: 233
Compressed size is: 147
ZLIB VERSION: 1.2.11
$ source ./generators/deactivate_conanbuild.sh
没有必要始终在 conanfile.py 中编写此逻辑。 有一些预定义的布局,你可以导入并在你的配方中直接使用。 例如,对于 CMake 用例,Conan 中已经定义了 cmake_layout()
from conan import ConanFile
from conan.tools.cmake import cmake_layout
class CompressorRecipe(ConanFile):
settings = "os", "compiler", "build_type", "arch"
generators = "CMakeToolchain", "CMakeDeps"
def requirements(self):
self.requires("zlib/1.2.11")
def build_requirements(self):
self.tool_requires("cmake/3.22.6")
def layout(self):
cmake_layout(self)
使用 validate() 方法为不支持的配置引发错误¶
当 Conan 加载 conanfile.py 时,将评估 validate() 方法,你可以使用它来执行输入设置的检查。 例如,如果你的项目不支持 macOS 上的 armv8 架构,你可以引发 ConanInvalidConfiguration 异常,使 Conan 返回一个特殊的错误代码。 这将表明用于设置或选项的配置不受支持。
...
from conan.errors import ConanInvalidConfiguration
class CompressorRecipe(ConanFile):
...
def validate(self):
if self.settings.os == "Macos" and self.settings.arch == "armv8":
raise ConanInvalidConfiguration("ARM v8 not supported in Macos")
使用 conanfile.py 的条件需求¶
你可以向 requirements() 方法 添加一些逻辑,以有条件地添加或删除需求。 例如,假设你想在 Windows 上添加额外的依赖项,或者你想使用系统的 CMake 安装而不是使用 Conan tool_requires
from conan import ConanFile
class CompressorRecipe(ConanFile):
# Binary configuration
settings = "os", "compiler", "build_type", "arch"
generators = "CMakeToolchain", "CMakeDeps"
def requirements(self):
self.requires("zlib/1.2.11")
# Add base64 dependency for Windows
if self.settings.os == "Windows":
self.requires("base64/0.4.0")
def build_requirements(self):
# Use the system's CMake for Windows
if self.settings.os != "Windows":
self.tool_requires("cmake/3.22.6")
使用 generate() 方法从软件包复制资源¶
在某些情况下,Conan 软件包包含对其软件包库的使用有用甚至必要的文件。 这些文件可以从配置文件、资源到项目正确构建或运行所需的特定文件不等。 使用 generate() 方法,你可以将这些文件从 Conan 缓存复制到你的项目文件夹,确保所有必需的资源都可以直接使用。
这是一个示例,展示了如何将依赖项的 resdirs
目录中的所有资源复制到你的项目中的 assets
目录中
import os
from conan import ConanFile
from conan.tools.files import copy
class MyProject(ConanFile):
...
def generate(self):
# Copy all resources from the dependency's resource directory
# to the "assets" folder in the source directory of your project
dep = self.dependencies["dep_name"]
copy(self, "*", dep.cpp_info.resdirs[0], os.path.join(self.source_folder, "assets"))
然后,在 conan install
步骤之后,所有这些资源文件都将被复制到本地,允许你在项目的构建过程中使用它们。 有关如何在 generate()
方法中导入软件包文件的完整示例,你可以参考关于使用 Dear ImGui 库的 博客文章,其中演示了如何根据图形 API 导入库的绑定。
另请参阅