理解 Conan 包布局¶
在上一个章节，我们介绍了可编辑包的概念，并提到它们之所以能够在进入可编辑模式后开箱即用，是因为 layout() 方法中信息的当前定义。让我们更详细地研究这个特性。
在本教程中，我们将继续使用在 可编辑包 教程中使用的 say/1.0 包和 hello/1.0 消费者。
请首先克隆源代码以重现此项目。您可以在 GitHub 上的 examples2 仓库 中找到它们。
$ git clone https://github.com/conan-io/examples2.git
$ cd examples2/tutorial/developing_packages/package_layout
注意
我们在本例中使用 CMake presets。这需要 CMake >= 3.23，因为 CMakeUserPresets.json 到 CMakePresets.json 的“include”功能自该版本起才受支持。如果您不想使用 presets，可以使用类似以下的方式：
cmake <path> -G <CMake generator> -DCMAKE_TOOLCHAIN_FILE=<path to
conan_toolchain.cmake> -DCMAKE_BUILD_TYPE=Release
如果您无法使用预设功能，Conan 将在每次运行 conan install 时显示确切的 CMake 命令。
正如您所见，主文件夹结构是相同的
.
├── hello
│ ├── CMakeLists.txt
│ ├── conanfile.py
│ └── src
│ └── hello.cpp
└── say
├── CMakeLists.txt
├── conanfile.py
├── include
│ └── say.h
└── src
└── say.cpp
这里的主要区别在于，我们在 say/1.0 ConanFile 中没有使用预定义的 cmake_layout()，而是声明了自己的自定义布局。让我们看看我们如何在 layout() 方法中描述信息，以便它既能在 Conan 本地缓存中创建包时工作，也能在包处于可编辑模式时工作。
import os
from conan import ConanFile
from conan.tools.cmake import CMake
class SayConan(ConanFile):
name = "say"
version = "1.0"
exports_sources = "CMakeLists.txt", "src/*", "include/*"
...
def layout(self):
## define project folder structure
self.folders.source = "."
self.folders.build = os.path.join("build", str(self.settings.build_type))
self.folders.generators = os.path.join(self.folders.build, "generators")
## cpp.package information is for consumers to find the package contents in the Conan cache
self.cpp.package.libs = ["say"]
self.cpp.package.includedirs = ["include"] # includedirs is already set to 'include' by
# default, but declared for completion
self.cpp.package.libdirs = ["lib"] # libdirs is already set to 'lib' by
# default, but declared for completion
## cpp.source and cpp.build information is specifically designed for editable packages:
# this information is relative to the source folder that is '.'
self.cpp.source.includedirs = ["include"] # maps to ./include
# this information is relative to the build folder that is './build/<build_type>', so it will
self.cpp.build.libdirs = ["."] # map to ./build/<build_type> for libdirs
def build(self):
cmake = CMake(self)
cmake.configure()
cmake.build()
让我们回顾一下 layout() 方法。您可以看到我们正在为 self.folders 和 self.cpp 设置值。让我们解释一下这些值的作用。
self.folders¶
定义 say 项目的源代码结构以及 Conan 生成的文件和构建产物将位于的文件夹。此结构与包是否处于可编辑模式或已导出并在 Conan 本地缓存中构建无关。让我们定义 say 包的文件夹结构。
say
├── CMakeLists.txt
├── conanfile.py
├── include
│ └── say.h
├── src
│ └── say.cpp
└── build
├── Debug --> Built artifacts for Debug
│ └── generators --> Conan generated files for Debug config
└── Release --> Built artifacts for Release
└── generators --> Conan generated files for Release config
由于我们的
CMakeLists.txt位于.文件夹中，因此self.folders.source被设置为.。我们将
self.folders.build设置为 ./build/Release 或 ./build/Debug，具体取决于build_type设置。这些是我们希望构建的二进制文件所在的文件夹。self.folders.generators文件夹是我们为 Conan 生成器创建的所有文件设置的位置。在这种情况下，所有由CMakeToolchain生成器生成的文件都将存储在那里。
注意
请注意，上述值适用于单配置 CMake 生成器。要支持多配置生成器，例如 Visual Studio，您应该对该布局进行一些更改。有关支持单配置和多配置的完整布局，请参阅 Conan 文档中的 cmake_layout()。
self.cpp¶
此属性用于定义**消费者将在何处找到包内容**（头文件、库等），具体取决于包是否处于可编辑模式。
cpp.package¶
首先，我们为 cpp.package 设置信息。这定义了包的内容及其相对于包在本地缓存中存储的文件夹的位置。请注意，定义此信息等同于在 package_info() 方法中定义 self.cpp_info。这是我们定义的信息：
self.cpp.package.libs：我们添加了say库，以便消费者知道他们应该与之链接。这等同于在package_info()方法中声明self.cpp_info.libs。self.cpp.package.libdirs：我们添加了lib文件夹，以便消费者知道他们应该在那里查找库。这等同于在package_info()方法中声明self.cpp_info.libdirs。请注意，cpp_info和cpp.package中libdirs的默认值都是["lib"]，因此我们可以省略该声明。self.cpp.package.includedirs：我们添加了include文件夹，以便消费者知道他们应该在那里查找库的头文件。这等同于在package_info()方法中声明self.cpp_info.includedirs。请注意，cpp_info和cpp.package中includedirs的默认值都是["include"]，因此我们可以省略该声明。
为了检查这些信息如何影响消费者，我们将首先在 say 包上执行一次 conan create。
$ cd say
$ conan create . -s build_type=Release
当我们调用 conan create 时，Conan 会将配方中声明的配方和源文件移动到本地缓存中一个配方文件夹，然后，它会创建一个单独的包文件夹来构建二进制文件并存储实际的包内容。如果您在 [YOUR_CONAN_HOME]/p 文件夹中进行检查，您会发现两个新的类似以下的文件夹。
提示
您可以使用 conan cache 命令或检查 conan create 命令的输出，来获取这些文件夹的精确位置。
<YOUR_CONAN_HOME>/p
├── sayb3ea744527a91 --> folder for sources
│ └── ...
│
└── say830097e941e10 --> folder for building and storing the package binaries
├── b
│ ├── build
│ │ └── Release
│ ├── include
│ │ └── say.h
│ └── src
│ ├── hello.cpp
│ └── say.cpp
└── p
├── include --> defined in cpp.package.includedirs
│ └── say.h
└── lib --> defined in cpp.package.libdirs
└── libsay.a --> defined in self.cpp.package.libs
您可以在其中识别出我们在 layout() 方法中定义的结构。如果您现在构建 hello 消费者项目，它将在本地缓存的该文件夹中，在 cpp.package 定义的位置查找 say 的所有头文件和库。
$ cd ../hello
$ conan install . -s build_type=Release
# Linux, MacOS
$ cmake --preset conan-release --log-level=VERBOSE
# Windows
$ cmake --preset conan-default --log-level=VERBOSE
...
-- Conan: Target declared 'say::say'
-- Conan: Library say found <YOUR_CONAN_HOME>p/say8938ceae216fc/p/lib/libsay.a
-- Created target CONAN_LIB::say_say_RELEASE STATIC IMPORTED
-- Conan: Found: <YOUR_CONAN_HOME>p/p/say8938ceae216fc/p/lib/libsay.a
-- Configuring done
...
$ cmake --build --preset conan-release
[ 50%] Building CXX object CMakeFiles/hello.dir/src/hello.cpp.o
[100%] Linking CXX executable hello
[100%] Built target hello
cpp.source 和 cpp.build¶
我们还在配方中定义了 cpp.source 和 cpp.build 属性。这些仅在包处于可编辑模式时使用，并指向消费者将用于查找头文件和二进制文件的位置。我们定义了：
self.cpp.source.includedirs设置为["include"]。此位置相对于我们设置为.的self.folders.source。在可编辑包的情况下，此位置将是我们项目所在的本地文件夹。self.cpp.build.libdirs设置为["."]。此位置相对于我们设置为 ./build/<build_type> 的self.folders.build。在可编辑包的情况下，此位置将指向 <local_folder>/build/<build_type>。
请注意，也可能存在其他 cpp.source 和 cpp.build 定义，具有不同的含义和目的。例如：
self.cpp.source.libdirs和self.cpp.source.libs可用于我们在源代码仓库中拥有预编译库的情况，例如提交到 git。它们不是构建的产物，而是源代码的一部分。self.cpp.build.includedirs可用于包含在构建时生成的头文件的文件夹，正如某些代码生成器在开始编译项目之前被构建调用时通常发生的那样。
为了检查这些信息如何影响消费者，我们将首先将 say 包置于可编辑模式并在本地构建它。
$ cd ../say
$ conan editable add . --name=say --version=1.0
$ conan install . -s build_type=Release
$ cmake --preset conan-release
$ cmake --build --preset conan-release
如果您现在检查 say 项目文件夹的内容，您会看到输出文件夹与我们使用 self.folders 定义的匹配。
.
├── CMakeLists.txt
├── CMakeUserPresets.json
├── build
│ └── Release --> defined in cpp.build.libdirs
│ ├── ...
│ ├── generators
│ │ ├── CMakePresets.json
│ │ ├── ...
│ │ └── deactivate_conanrun.sh
│ └── libsay.a --> no need to define
├── conanfile.py
├── include --> defined in cpp.source.includedirs
│ └── say.h
└── src
├── hello.cpp
└── say.cpp
现在 say 包处于可编辑模式，如果我们构建 hello 消费者项目，它将在 cpp.source 和 cpp.build 定义的文件夹中查找 say 的所有头文件和库。
$ cd ../hello
$ conan install . -s build_type=Release
# Linux, MacOS
$ cmake --preset conan-release --log-level=VERBOSE
# Windows
$ cmake --preset conan-default --log-level=VERBOSE
...
-- Conan: Target declared 'say::say'
-- Conan: Library say found <local_folder>/examples2/tutorial/developing_packages/package_layout/say/build/Release/libsay.a
-- Conan: Found: <local_folder>/examples2/tutorial/developing_packages/package_layout/say/build/Release/libsay.a
-- Configuring done
...
$ cmake --build --preset conan-release
[ 50%] Building CXX object CMakeFiles/hello.dir/src/hello.cpp.o
[100%] Linking CXX executable hello
[100%] Built target hello
$ conan editable remove --refs=say/1.0
注意
请注意，我们没有定义 self.cpp.build.libs = ["say"]。这是因为在 self.cpp.source 和 self.cpp.build 中设置的信息将与在 self.cpp.package 中设置的信息合并，因此您只需要定义可编辑包发生变化的内容。出于相同的原因，您也可以省略设置 self.cpp.source.includedirs = ["include"]，但为了展示 cpp.source 的用法，我们将其保留。