理解使用 conanfile.py 与 conanfile.txt 的灵活性¶
在之前的例子中,我们在
[requires]
zlib/1.3.1
[tool_requires]
cmake/3.27.9
[generators]
CMakeDeps
CMakeToolchain
对于简单情况,使用
请首先克隆源代码以重新创建此项目。您可以在 GitHub 的 examples2 仓库中找到它们。
$ git clone https://github.com/conan-io/examples2.git
$ cd examples2/tutorial/consuming_packages/conanfile_py
检查文件夹内容,并注意内容与之前的例子相同,但用
.
├── CMakeLists.txt
├── conanfile.py
└── src
└── main.c
请记住,在之前的例子中,
[requires]
zlib/1.3.1
[tool_requires]
cmake/3.27.9
[generators]
CMakeDeps
CMakeToolchain
我们将把相同的信息转换为
from conan import ConanFile
class CompressorRecipe(ConanFile):
settings = "os", "compiler", "build_type", "arch"
generators = "CMakeToolchain", "CMakeDeps"
def requirements(self):
self.requires("zlib/1.3.1")
def build_requirements(self):
self.tool_requires("cmake/3.27.9")
为了创建 Conan recipe,我们声明了一个继承自 ConanFile
类的类。这个类具有不同的类属性和方法
settings 类属性定义了项目范围的变量,例如编译器、其版本或操作系统本身,这些变量在我们构建项目时可能会改变。这与 Conan 如何管理二进制兼容性有关,因为这些值将影响 Conan 包的 package ID 的值。我们将在后面解释 Conan 如何使用此值来管理二进制兼容性。
generators 类属性指定了当我们调用 conan install 命令时将运行哪些 Conan 生成器。在本例中,我们像在
conanfile.txt 中一样添加了 CMakeToolchain 和 CMakeDeps。在 requirements() 方法中,我们使用
self.requires()
方法来声明zlib/1.3.1 依赖项。在 build_requirements() 方法中,我们使用
self.tool_requires()
方法来声明cmake/3.27.9 依赖项。
注意
将依赖项添加到 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
到目前为止,我们已经实现了使用
使用 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.3.1")
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.27.9")
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)必须为每个配置(作为不同的构建类型 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 中编写此逻辑。有一些预定义的布局可以导入并直接在你的 recipe 中使用。例如,对于 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.3.1")
def build_requirements(self):
self.tool_requires("cmake/3.27.9")
def layout(self):
cmake_layout(self)
使用 validate() 方法为不支持的配置引发错误¶
validate() 方法 在 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.3.1")
# 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.27.9")
使用 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 导入库的绑定。
使用 build() 方法和 conan build
命令¶
如果你的 recipe 实现了 build()
方法,那么就可以通过单个命令自动调用完整的 conan install + cmake <configure> + cmake <build>
流程(或者调用 build()
方法使用的构建系统)。尽管这可能不是典型的开发者流程,但在某些情况下它可能是一个方便的快捷方式。
让我们将这个 build()
方法添加到我们的 recipe 中
from conan import ConanFile
from conan.tools.cmake import CMake
class CompressorRecipe(ConanFile):
settings = "os", "compiler", "build_type", "arch"
generators = "CMakeToolchain", "CMakeDeps"
...
def build(self):
cmake = CMake(self)
cmake.configure()
cmake.build()
所以现在我们只需调用 conan build .
$ conan build .
...
Graph root
conanfile.py: ...\conanfile.py
Requirements
zlib/1.2.11#bfceb3f8904b735f75c2b0df5713b1e6 - Downloaded (conancenter)
Build requirements
cmake/3.22.6#32cced101c6df0fab43e8d00bd2483eb - Downloaded (conancenter)
======== Calling build() ========
conanfile.py: Calling build()
conanfile.py: Running CMake.configure()
conanfile.py: RUN: cmake -G "Visual Studio 17 2022" -DCMAKE_TOOLCHAIN_FILE="conan_toolchain.cmake"
...
conanfile.py: Running CMake.build()
conanfile.py: RUN: cmake --build "...\conanfile_py" --config Release
我们将看到它是如何首先安装依赖项,然后调用 build()
方法,该方法为我们调用 CMake 配置和构建步骤。因为 conan build .
内部执行 conan install
,所以它可以接收与 conan install
相同的参数(profile、settings、options、lockfile 等)。
注意
最佳实践
conan build
命令无意取代或改变使用 CMake 和其他构建工具以及其 IDE 的典型开发者流程。它只是在我们想要轻松地本地构建一个项目而无需输入多个命令或使用 IDE 的情况下的一个方便快捷方式。