GitLab 包注册表中的 Conan 1 包

在项目的包注册表中发布 Conan 包。然后在需要使用它们作为依赖项时安装这些包。

要将 Conan 包发布到包注册表，请将包注册表添加为远程并进行身份验证。

然后您可以运行 conan 命令并将您的包发布到包注册表。

有关 Conan 包管理器客户端使用的特定 API 端点的文档，请参阅 Conan v1 API 或 Conan v2 API。

学习如何 构建 Conan 1 包。

将包注册表添加为 Conan 远程

要运行 conan 命令，您必须将包注册表添加为项目或实例的 Conan 远程。然后您可以向包注册表发布包并从包注册表安装包。

为您的项目添加远程

设置一个远程，这样您可以在项目中使用包，而无需在每个命令中都指定远程名称。

当您为项目设置远程时，对您的包名称没有限制。但是，您的命令必须包含完整的配方，包括用户和通道，例如 package_name/version@user/channel。

要添加远程：

1. 在您的终端中，运行以下命令：

   conan remote add gitlab https://gitlab.example.com/api/v4/projects/<project_id>/packages/conan

2. 通过在 Conan 命令末尾添加 --remote=gitlab 来使用该远程。

   例如：

   conan search Hello* --remote=gitlab

为您的实例添加远程

使用单个远程来访问整个 GitLab 实例中的包。

但是，使用此远程时，您必须遵循这些 包命名限制。

要添加远程：

1. 在您的终端中，运行以下命令：

   conan remote add gitlab https://gitlab.example.com/api/v4/packages/conan

2. 通过在 Conan 命令末尾添加 --remote=gitlab 来使用该远程。

   例如：

   conan search 'Hello*' --remote=gitlab

实例远程的包配方命名约定

标准的 Conan 配方约定是 package_name/version@user/channel，但如果您使用的是 实例远程，配方中的 user 必须是加号（+）分隔的项目路径。

示例配方名称：

项目远程 具有更灵活的命名约定。

身份验证到包注册表

GitLab 需要身份验证才能上传包，以及从私有和内部项目安装包。（但是，您无需身份验证即可从公共项目安装包。）

要对包注册表进行身份验证，您需要以下之一：

• 一个 个人访问令牌，范围设置为 api。
• 一个 部署令牌，范围设置为 read_package_registry、write_package_registry 或两者。
• 一个 CI 作业令牌。

将您的凭据添加到 GitLab 远程

将您的令牌与 GitLab 远程关联，这样您就不必在每个 Conan 命令中明确添加令牌。

先决条件：

• 您必须拥有身份验证令牌。
• Conan 远程 必须已配置。

在终端中运行此命令。在此示例中，远程名称为 gitlab。使用您远程的名称。

conan user <gitlab_username or deploy_token_username> -r gitlab -p <personal_access_token or deploy_token>

现在当您使用 --remote=gitlab 运行命令时，您的用户名和密码将包含在请求中。

为您的项目设置默认远程（可选）

如果您想与 GitLab 包注册表交互而不必指定远程，您可以告诉 Conan 始终为您的包使用包注册表。

在终端中运行以下命令：

conan remote add_ref Hello/0.1@mycompany/beta gitlab

如果您没有设置默认用户或远程，您仍然可以在命令中包含用户和远程：

CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> <conan command> --remote=gitlab

发布 Conan 包

将 Conan 包发布到包注册表，这样任何可以访问项目的人都可以使用该包作为依赖项。

先决条件：

• Conan 远程 必须已配置。
• 必须已配置与包注册表的 身份验证。
• 必须存在本地 Conan 包。
  • 对于实例远程，包必须符合 命名约定。
• 您必须拥有项目 ID，它显示在 项目概览页面 上。

要发布包，请使用 conan upload 命令：

conan upload Hello/0.1@mycompany/beta --all

使用 CI/CD 发布 Conan 包

要在 GitLab CI/CD 中使用 Conan 命令，您可以在命令中使用 CI_JOB_TOKEN 替代个人访问令牌。

您可以在 .gitlab-ci.yml 文件中为每个 Conan 命令提供 CONAN_LOGIN_USERNAME 和 CONAN_PASSWORD。例如：

create_package:
  image: conanio/gcc7
  stage: deploy
  script:
    - conan remote add gitlab ${CI_API_V4_URL}/projects/$CI_PROJECT_ID/packages/conan
    - conan new <package-name>/0.1 -t
    - conan create . <group-name>+<project-name>/stable
    - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload <package-name>/0.1@<group-name>+<project-name>/stable --all --remote=gitlab
  environment: production

可用作 CI 文件基础的额外 Conan 图像可在 Conan 文档 中找到。

重新发布具有相同配方的包

当您发布与现有包具有相同配方（package-name/version@user/channel）的包时，重复文件将成功上传并且可以通过 UI 访问。但是，当安装该包时，只返回最新发布的包。

安装 Conan 包

从包注册表安装 Conan 包，以便您可以将其用作依赖项。您可以从您的实例或项目的范围安装包。如果有多个包具有相同的配方，当您安装包时，将检索最新发布的包。

Conan 包通常通过使用 conanfile.txt 文件作为依赖项来安装。

先决条件：

• Conan 远程 必须已配置。
• 对于私有和内部项目，您必须配置与包注册表的 身份验证。

1. 在您想要将包作为依赖项安装的项目中，打开 conanfile.txt。或者，在您的项目根目录中，创建一个名为 conanfile.txt 的文件。

2. 将 Conan 配方添加到文件的 [requires] 部分：

   [requires]
   Hello/0.1@mycompany/beta
   
   [generators]
   cmake

3. 在您的项目根目录中，创建一个 build 目录并切换到该目录：

   mkdir build && cd build

4. 安装 conanfile.txt 中列出的依赖项：

   conan install .. <options>

删除 Conan 包

有两种方法可以从 GitLab 包注册表中删除 Conan 包。

• 从命令行，使用 Conan 客户端：

  conan remove Hello/0.2@user/channel --remote=gitlab

  您必须在此命令中明确包含远程，否则包只会从您的本地系统缓存中删除。

  此命令会删除包注册表中的所有配方和二进制包文件。

• 从 GitLab 用户界面：

  转到您项目的 Deploy > Package registry。通过选择 Remove repository ( ) 来删除包。

在包注册表中搜索 Conan 包

要按完整或部分包名称或精确配方进行搜索，请运行 conan search 命令。

• 要搜索具有特定包名称的所有包：

  conan search Hello --remote=gitlab

• 要搜索部分名称，例如所有以 He 开头的包：

  conan search He* --remote=gitlab

您的搜索范围取决于您的 Conan 远程配置：

• 如果您为您的 实例 配置了远程，您的搜索将包括您有权访问的所有项目。这包括您的私有项目以及所有公共项目。

• 如果您为 项目 配置了远程，您的搜索将包括目标项目中的所有包，只要您有权访问它。

从包注册表获取 Conan 包信息

conan info 命令返回有关包的信息：

conan info Hello/0.1@mycompany/beta

下载 Conan 包

您可以将 Conan 包的配方和二进制文件下载到本地缓存，而无需使用使用 conan download 命令的设置。

先决条件：

• Conan 远程 必须已配置。
• 对于私有和内部项目，您必须配置与包注册表的 身份验证。

下载所有二进制包

您可以从包注册表下载与配方关联的所有二进制包。

要下载所有二进制包，请运行以下命令：

conan download Hello/0.1@foo+bar/stable --remote=gitlab

下载配方文件

您可以只下载配方文件而不下载任何二进制包。

要下载配方文件，请运行以下命令：

conan download Hello/0.1@foo+bar/stable --remote=gitlab --recipe

下载特定的二进制包

您可以通过引用其包引用（在 Conan 文档中称为 package_id）来下载单个二进制包。

要下载特定的二进制包，请运行以下命令：

conan download Hello/0.1@foo+bar/stable:<package_reference> --remote=gitlab

支持的 CLI 命令

GitLab Conan 存储库支持以下 Conan CLI 命令：

• conan upload：将您的配方和包文件上传到包注册表。
• conan install：从包注册表安装 Conan 包，包括使用 conanfile.txt 文件。
• conan download：将包配方和二进制文件下载到本地缓存而不使用设置。
• conan search：搜索包注册表中的公共包以及您有权查看的私有包。
• conan info：查看来自包注册表的给定包的信息。
• conan remove：从包注册表中删除包。

提取 Conan 元数据

当您上传 Conan 包时，GitLab 会自动从 conaninfo.txt 文件中提取元数据。此元数据包括：

• 包设置（如 os、arch、compiler 和 build_type）
• 包选项
• 包要求和依赖项

Conan 版本控制

Conan 1 版本控制在包注册表中提供包的不变性。当您更改配方或包而不更改其版本时，Conan 会计算一个唯一标识符（版本）来跟踪这些更改。

版本类型

Conan 使用两种类型的版本：

• 配方版本 (RREV)：在导出配方时生成。默认情况下，Conan 使用配方清单的校验和哈希计算配方版本。
• 包版本 (PREV)：在构建包时生成。Conan 使用包内容的哈希计算包版本。

启用版本控制

在 Conan 1.x 中，版本控制默认不启用。要启用版本控制，您必须：

• 在您的 _conan.conf_ 文件的 [general] 部分添加 revisions_enabled=1（首选）。
• 设置 CONAN_REVISIONS_ENABLED=1 环境变量。

引用版本

您可以按以下格式引用包：

上传版本

要将所有版本及其二进制文件上传到 GitLab 包注册表：

conan upload package_name/version@user/channel#* --all --remote=gitlab

当您上传多个版本时，它们从最旧到最新上传。相对顺序在注册表中保留。

搜索版本

要在 Conan v1 中搜索特定配方的所有版本：

conan search package_name/version@user/channel --revisions --remote=gitlab

此命令显示指定配方及其版本哈希和创建日期的所有可用版本。

要获取特定版本的详细信息：

conan search package_name/version@user/channel#revision_hash --remote=gitlab

此命令向您显示该版本可用的特定二进制包。

删除带版本的包

您可以在不同粒度级别删除包：

删除特定配方版本

要删除特定配方版本及其所有关联的二进制包：

conan remove package_name/version@user/channel#revision_hash --remote=gitlab

删除特定配方版本的包

要删除与特定配方版本关联的所有包：

conan remove package_name/version@user/channel#revision_hash --packages --remote=gitlab

删除版本中的特定包

要删除配方版本中的特定包，您可以使用以下任一命令：

conan remove package_name/version@user/channel#revision_hash -p package_id --remote=gitlab

或者：

conan remove package_name/version@user/channel#revision_hash:package_id --remote=gitlab

不可变版本工作流

版本设计为不可变的。当您修改配方或其源代码时：

• 在导出配方时会创建新的配方版本。
• 属于先前配方版本的任何现有二进制文件都不包含在内。您必须为新配方版本构建新的二进制文件。
• 当安装包时，Conan 会自动检索最新版本，除非您指定版本。

对于包二进制文件，每个配方版本和包引用（在 Conan 文档中称为 package_id）应该只包含一个包版本。同一配方版本和包 ID 的多个包版本表明包被不必要地重新构建了。

故障排除

使输出详细

在排查 Conan 问题时获取更详细的输出：

export CONAN_TRACE_FILE=/tmp/conan_trace.log # Or SET in windows
conan <command>

您可以在 Conan 文档 中找到更多日志记录提示。

SSL 错误

如果您使用自签名证书，有两种方法可以管理 Conan 的 SSL 错误：

• 使用 conan remote 命令禁用 SSL 验证。
• 将您的服务器 crt 文件附加到 cacert.pem 文件。

在 Conan 文档 中阅读更多相关信息。