核心准则

最佳实践

• build() 方法应保持简洁，构建准备工作应放在 generate() 中完成：配方（recipe）的 generate() 方法旨在尽可能地准备构建。调用 conan install 的用户将执行此方法，生成的文件应允许用户尽可能轻松地进行“原生”构建（直接调用“cmake”、“meson”等）。因此，尽可能避免在 build() 方法中放置任何逻辑，并将其移至 generate() 方法，有助于开发者在本地实现与通过本地缓存中的 conan create 构建所产生的相同的构建效果。

• 在生产环境中始终使用自己的配置文件，而不是依赖自动检测的配置文件，因为自动检测的结果会随时间变化，导致意外结果。配置文件（以及许多其他配置）可以通过 conan config install 进行管理。

• 开发者不应有权限上传到服务器上的“开发”和“生产”仓库。只有 CI 构建在服务器上具有写入权限。开发者应只拥有读取权限，并且最多只能访问一些用于与同事协作和共享的“试验”仓库，但这些仓库中的包绝不能用于、移动或复制到开发或生产仓库。

• test_package 的目的是验证包的正确创建，而非功能测试。test_package 的目的是检查包是否已正确创建（即，它是否已将头文件、库等正确打包到正确的文件夹中），而不是检查包的功能是否正确。因此，它应尽可能保持简单，例如构建并运行一个使用头文件并链接到已打包库的可执行文件就足够了。此类执行也应尽可能简单。任何类型的单元测试和功能测试都应在 build() 方法中完成。

• 所有输入源必须对所有二进制配置通用：所有“源”输入，包括 conanfile.py、conandata.yml、exports 和 exports_source、source() 方法以及在 source() 方法中应用的补丁，都不能以任何条件（平台、操作系统或编译器）为基础，因为它们在所有配置之间共享。此外，所有这些内容的行尾符应保持一致，建议在所有平台中始终只使用换行符（line-feeds），并且不要在 Windows 中转换为或检出为 crlf，因为这会导致不同的配方修订版本。

• 尽可能保持 ``python_requires`` 的简洁性。避免传递性 python_requires，使其尽可能地精简，最多在“扁平”结构中明确要求它们，而不要让 python_requires 依赖其他 python_requires。如果非严格必要，请避免继承（通过 python_requires_extend），并竭力避免多重继承，因为它极其复杂，且其工作方式与 Python 内置的继承机制不同。

• 目前，Conan 缓存不支持并发。请避免任何形式的并发或并行操作，例如，不同的并行 CI 作业应使用不同的缓存（通过 CONAN_HOME 环境变量）。未来这可能会改变，我们也将致力于在缓存中提供并发支持，但在那之前，请为并发任务使用独立的缓存。

• 避免将“force”和“override”特性作为版本控制机制。 不建议将 force 和 override 特性作为通用的版本冲突解决方案，而应仅将其作为解决版本冲突的临时性替代方案。应尽可能避免使用它们，推荐的方法是更新图中的版本或版本范围，以避免不使用覆盖和强制的冲突。

• 请不要滥用 ‘tool_requires’。它仅用于在“构建”上下文中运行的可执行文件，例如 cmake 和 ninja，而不适用于库或类似库的依赖项，后者必须使用 requires 或 test_requires。

• 调用 Conan 时，位置参数应首先指定，在任何命名参数之前。例如，conan install . -s="os=Windows" 是正确的，但 conan install -s="os=Windows" . 是错误的。同样，建议在命名参数的名称和值之间使用 = 而不是空格。这是为了避免在解析命令行参数时出现一些歧义情况。

• 强烈不建议将 user/channel 用于任何质量、阶段、成熟度或可变信息。channel 部分是遗留产物，在大多数情况下应避免使用，或者使用固定字符串如 stable。user 可用于组织内部的私有包，而对于来自 ConanCenter 或 conan-center-index Github 仓库的包，建议不带任何 user 或 channel 使用它们，例如 zlib/1.3.1 ConanCenter 引用，即使是对这些第三方库的配方和包进行定制也是如此。

• 管理包质量、阶段或成熟度升级的方式是使用不同的服务器仓库，而开发者众所周知的最佳实践建议通过在这些不同的服务器仓库之间进行升级（复制）不可变工件或包来管理流水线，例如在包通过某些质量检查后，将其从 staging 仓库复制到 production 仓库。但非常重要的是，这种升级不能以任何方式更改这些包，它们必须是完全不可变的，甚至不能更改其 user/channel，这就是为什么上面一点不鼓励使用 user 和 channel 的原因，包和工件必须是不可变的。

禁用实践

• Conan 不可重入：不能从 Conan 自身内部调用 Conan 进程。这包括从配方代码、钩子、插件以及基本上任何在 Conan 被调用时已执行的代码中调用 Conan。这样做将导致未定义行为。例如，从 conanfile.py 中运行 conan search 是无效的。这包括间接调用，例如当构建脚本（如 CMakeLists.txt）已经由于 Conan 调用而执行时，从该构建脚本中运行 Conan。出于同样的原因，Conan Python API 不能从配方中使用：Conan Python API 只能从 Conan 自定义命令或用户 Python 脚本中调用，但绝不能从 conanfile.py 配方、钩子、扩展、插件或 Conan 执行的任何其他代码中调用。

• 配方中的设置和配置（conf）是只读的：设置和配置不能在配方中定义或赋值。不应在配方中执行类似 self.settings.compiler = "gcc" 的操作。这是未定义行为，可能随时崩溃，或者直接被忽略。设置和配置只能在配置文件中、命令行参数中或在 profile.py 插件中定义。

• 配方保留名称：Conan conanfile.py 配方的用户属性和方法应始终以 _ 开头。Conan 为所有属性和方法保留“public”命名空间，为私有属性和方法保留 _conan。使用任何未文档化的 Python 函数、方法、类、属性，即使它在 Python 意义上是“public”的，如果该元素未在此文档中进行说明，则会产生未定义行为。

• Conan 工件是不可变的：Conan 包和工件一旦进入 Conan 缓存，就被认为是不可变的。任何尝试修改导出的源、配方、conandata.yml 或任何已导出或已打包工件的行为都是未定义行为。例如，不能在 package_info() 方法或 package_id() 方法内部修改包的内容，这些方法绝不应修改、删除或在包内部创建新文件。如果您需要修改某个包，可以使用自己的自定义 deployer。

• Conan 缓存路径是内部实现细节：Conan 缓存路径是一个内部实现细节。Conan 配方提供了像 self.build_folder 这样的抽象来表示关于文件夹的必要信息，以及像 conan cache path 这样的命令来获取当前文件夹的信息。Conan 缓存可以在调试时以只读方式检查，但不允许通过 Conan 命令行或公共 API 以外的任何方式编辑、修改或删除 Conan 缓存中的工件或文件。

• 配方中使用的源必须是不可变的。一旦配方被导出到 Conan 缓存中，就预期其源是不可变的，也就是说，将来检索这些源时将始终检索到完全相同的源。不允许使用移动目标，例如 git 分支或服务器上持续重写的下载文件。git 检出必须是不可变的标签或提交，download()/get() 必须使用校验和来验证服务器文件没有改变。不使用不可变源将导致未定义行为。