常见问题¶

另请参阅

Conan 背后有一个很棒的社区，用户们在 Cpplang Slack 中互相帮助。请加入我们的 #conan 频道！

故障排除¶

错误：缺少预构建包¶

在安装包时（使用 conan install 或 conan create），您可能会收到如下错误：

ERROR: Missing binary: zlib/1.3.1:b1d267f77ddd5d10d06d2ecf5a6bc433fbb7eeed

zlib/1.3.1: WARN: Can't find a 'zlib/1.3.1' package binary 'b1d267f77ddd5d10d06d2ecf5a6bc433fbb7eeed' for the configuration:
[settings]
arch=x86_64
build_type=Release
compiler=apple-clang
compiler.cppstd=gnu11
compiler.libcxx=libc++
compiler.version=14
os=Macos
[options]
fPIC=True
shared=False

ERROR: Missing prebuilt package for 'zlib/1.3.1'. You can try:
    - List all available packages using 'conan list "{ref}:*" -r=remote'
    - Explain missing binaries: replace 'conan install ...' with 'conan graph explain ...'
    - Try to build locally from sources using the '--build=zlib/1.3.1' argument

More Info at 'https://docs.conan.org.cn/en/2/knowledge/faq.html#error-missing-prebuilt-package'

这意味着包配方 zlib/1.3.1 存在，但由于某种原因，您的当前设置或选项没有预编译包。可能是包创建者根本没有构建和共享预构建包，而只上传了包配方，或者他们只为某些平台或编译器提供了包。例如，包创建者从 apple-clang 11 的配方构建了包，但您正在使用 apple-clang 14。您可能还需要检查您的包ID模式，因为它可能影响可用的包。

默认情况下，Conan 不从源代码构建包。有几种方法可以解决此错误：

您可以尝试根据您的设置从源代码构建包，指定一些构建策略作为参数，例如 --build zlib* 或 --build missing。如果包配方和源代码适用于您的设置，您将在本地构建好二进制文件并可供使用。
如果从源代码构建失败，并且您正在使用 conancenter 远程，您可以在 Conan Center Index 仓库中提出问题。

错误：无效设置¶

有时，当您指定一个默认设置中不存在的设置时，可能会收到如下消息：

$ conan install . -s compiler.version=4.19 ...

ERROR: Invalid setting '4.19' is not a valid 'settings.compiler.version' value.
Possible values are ['4.4', '4.5', '4.6', '4.7', '4.8', '4.9', '5.1', '5.2', '5.3', '5.4', '6.1', '6.2']

这不意味着 Conan 不支持该编译器版本，只是它不在当前的默认设置中。您可以在用户主文件夹下的 ~/.conan2/settings.yml 找到一个设置文件，您可以修改、编辑、添加任何设置或任何值，如果需要，还可以进行任意嵌套。请参阅 settings.yml，了解如何自定义您的设置以随意建模您的二进制文件。

只要您的团队或用户拥有相同的设置（settings.yml 和 settings_user.yml 可以通过 conan config install 命令轻松共享），一切都将正常工作。settings.yml 文件只是一种机制，旨在让用户就典型设置的通用拼写达成一致。此外，如果您认为某些设置对许多其他 Conan 用户有用，请将其作为问题或拉取请求提交，以便将其包含在未来的版本中。

某些内置帮助程序或集成，例如 CMake 或 CMakeToolchain，可能不理解新添加的设置，如果您向现有设置添加了新的意外值，它们可能无法使用甚至会失败。像 CMake 这样的帮助程序是简单的实用程序，用于将 Conan 设置转换为相应的构建系统语法和命令行参数，因此它们可以被扩展或替换为您自己的、能够处理您私有设置的帮助程序。

错误：AuthenticationException：¶

如果 Conan 发出的 HTTP 请求中没有或存在错误的认证凭据，则可能会出现此错误。要获取更多信息，请尝试为 HTTP 连接启用调试级别。

import http.client
http.client.HTTPConnection.debuglevel = 1

一个错误来源可能是 .netrc 文件，该文件被 requests 库所尊重。

错误：在 Linux 和 Windows 中获取到不同的修订版本¶

Git 在 Windows 系统中（默认情况下）会使用 CRLF 行尾符检出文件，这实际上会产生与 Linux 中使用 LF 行尾符的文件不同的文件。由于文件不同，Conan 配方修订版将不同于在 Linux 等其他平台中计算的修订版，导致在其他修订版中缺少相应的二进制文件。

Conan 不会以任何方式规范化或更改源文件，这不是它的职责，并且存在破坏事物的风险。源代码管理是更改文件的应用程序，因此这是处理此问题的更正确的地方。有必要指示 Git 以相同的行尾符进行检出。可以通过多种方式完成此操作，例如，在项目仓库中添加一个 .gitattributes 文件，内容如下：

* text eol=lf

另一种方法是更改 .gitconfig 以进行全局更改。Windows 中的现代编辑器（即使是记事本）也可以完美地处理带有 LF 的文件，不再需要更改行尾符。

在 conanfile.py 配方中为依赖项定义选项不起作用¶

Conan 以深度优先的方式扩展依赖图，这对于实现许多非常特殊的 C/C++ 传播逻辑（头文件、静态和共享库、应用程序、工具依赖、测试依赖、冲突、覆盖等）非常重要。

这意味着当一个 conanfile.py 声明了类似以下内容时：

class MyPkg(ConanFile):
    name = "mypkg"
    version = "0.1"
    default_options = {"zlib/*:shared": True}
    # Or
    def requirements(self):
        self.requires("zlib/1.3", options={"shared": True})

它可能无法总是被遵守，并且 zlib 依赖项最终可能具有不同的 shared=False 选项值。这种在配方中为依赖项定义选项值的做法仅在以下情况下有效：

图中没有其他包依赖于 zlib
图中有其他包依赖于 zlib，但 mypkg/0.1 是第一个被要求的依赖（依赖图中的第一个分支）。这意味着 requires = "mypkg/0.1", "zlib/1.3" 将会起作用，并使 zlib 成为共享库，但 requires = "zlib/1.3", "mypkg/0.1" 会首先展开 zlib 的默认值（即 shared=False），当 mypkg/0.1 被计算时，再将 zlib 更改为 shared=True 将为时已晚。

如果存在某些配方在依赖项的某个选项下完全无法工作，建议在配方中定义一个 validate() 方法，以确保如果上游依赖项由于某种原因没有正确的选项值，它将引发错误。

Conan 可能会在 Conan 命令的输出中显示一些（不保证是详尽的）这些问题，请仔细阅读。

Options conflicts
    liba/0.1:myoption=1 (current value)
        libc/0.1->myoption=2
    It is recommended to define options values in profiles, not in recipes

通常，更建议在配置文件中定义选项值，而不是在配方中。配方中定义的选项总是优先于配置文件中定义的选项。

即使使用版本范围，也会出现版本冲突¶

在安装依赖项时，可能会出现版本冲突错误消息，例如：

...
Version conflict: Conflict between math/1.0.1 and math/1.0 in the graph

这篇关于版本冲突的教程总结了相同包依赖项的不同版本如何在依赖图中发生冲突以及如何解决这些冲突。

然而，在某些情况下冲突并不那么明显，例如当存在混合版本范围和固定依赖项时，如下所示：

def requirements(self):
  self.requires("libb/1.0")  # requires liba/[>=1.0 <2]
  self.requires("libc/1.0")  # requires liba/1.0

并且恰好 libb/1.0 对 liba/[>=1.0 <2] 有传递性需求，而 libc/1.0 要求 liba/1.0，并且存在 liba/1.1 或更高版本的包。在这种情况下，Conan 也可能会抛出“版本冲突”错误。

根本原因在于，解决版本范围在图中定义的所有可能约束的联合兼容性是一个已知的 NP-hard 问题，即 SAT 求解器问题。在 Conan 中评估这个 NP-hard 问题中的每个假设都非常昂贵，因为它通常需要：在所有定义的远程仓库中查找版本/修订版，然后下载该版本/修订版的压缩文件，解压它们，加载并用 Python 解析和评估它们，最后执行所有图计算处理，这涉及将 C/C++ 需求特性传播到已经展开的图中，从而可能产生冲突。这使得该问题在实践中变得难以处理，可能需要等待数小时才能完成。

因此，Conan 没有这样做，而是使用了一种不需要回溯的“贪婪”算法，但仍会尽可能地调和版本范围与固定版本。关于这一点，最重要的一点是 Conan 实现了“深度优先”图扩展，按照声明的顺序评估 requires。了解这一点有助于解决此冲突。在上述情况下，错误发生是因为 libb/1.0 首先被展开，它找到了对 liba/[>=1.0 <2] 的需求，并且由于之前没有找到对 liba 的其他约束，它自由地解析为最新的 liba/1.1。稍后当 libc/1.0 被展开时，它找到了对 liba/1.0 的需求，但为时已晚，因为它将与之前的 liba/1.1 发生冲突。回溯到之前的假设是将问题转换为 NP-hard 的“回溯”部分，因此算法在此停止并引发冲突。

这可以通过简单地交换 requires 的顺序来解决。

def requirements(self):
  self.requires("libc/1.0")  # requires liba/1.0
  self.requires("libb/1.0")  # requires liba/[>=1.0 <2]

如果 libc/1.0 首先被展开，它会解析为 liba/1.0。稍后当 libb/1.0 被展开时，其传递性需求 liba/[>=1.0 <2] 可以被之前的 liba/1.0 成功满足，因此它可以成功解析图。

一般最佳实践是：

对于相同的依赖项，尝试在所有地方使用相同的方法：对于该特定依赖项，要么在所有地方使用版本范围，要么在所有地方使用固定版本。
保持版本一致。如果使用版本范围，请尝试在所有地方使用相同的版本范围。
优先声明使用固定版本的依赖项，而不是版本范围
使用 conan graph info ... --format=html > graph.html 图形交互式输出以理解和导航冲突。

Conan 将其输出重定向到标准错误 (stderr)¶

正如命令参考中所解释的，Conan 的设计是将日志信息重定向到标准错误输出 (stderr)，而命令的实际结果则发送到标准输出 (stdout)。

这样做是为了让用户能够轻松地将 Conan 命令的输出重定向到文件或其他进程，而不会将日志信息与实际结果混淆。

例如，运行以下命令：

$ conan graph info --requires=zlib/1.3.1 --format=json > graph.json

...

======== Computing dependency graph ========
Graph root
    cli
Requirements
    zlib/1.3.1#b8bc2603263cf7eccbd6e17e66b0ed76 - Cache

======== Computing necessary packages ========
Connecting to remote 'conancenter' anonymously
Requirements
    zlib/1.3.1#b8bc2603263cf7eccbd6e17e66b0ed76:dbb40f41e6e9a5c4a9a1fd8d9e6ccf6d92676c92#8976086f07d37e3f6288e2fccf9650ae - Cache

将创建一个名为 graph.json 的文件，其中包含命令的 JSON 输出，但不会包含任何日志信息，日志信息将打印到控制台。

请注意，这种方法在许多命令行工具（例如 git 和 curl）中很常见，并非 Conan 所特有。