捕获 Git SCM 信息¶
在 Conan 包配方中处理源代码主要有两种策略
第三方代码:当
conanfile.py
配方打包第三方代码(例如开源库)时,通常最好使用source()
方法下载或克隆该库的源代码。ConanCenter 的conan-center-index
仓库就是采用这种方法。您自己的代码:当
conanfile.py
配方打包您自己的代码时,通常最好将conanfile.py
放在与源代码相同的仓库中。然后,有两种实现可复现性的方法:使用
exports_sources
(或export_source()
方法)在 Conan 包中随配方一起捕获源代码副本。这非常简单实用,建议在大多数情况下使用。如果无法将源代码与 Conan 配方一同存储,例如当包供无权访问源代码的用户使用时,那么当前的SCM 捕获方法将是解决方案。
在SCM 捕获方法中,不是捕获代码本身的副本,而是捕获该代码的“坐标”。在 Git
的情况下,即仓库的 url
和 commit
。如果配方需要从源代码构建,它将使用该信息获取克隆;如果尝试此操作的用户未被授权,则过程将失败。他们仍然可以使用我们分发的预编译二进制文件,但无法从源代码构建或访问代码。
我们来看一个示例。请首先克隆源代码以重新创建此项目。您可以在 GitHub 上的 examples2 仓库中找到它们
$ git clone https://github.com/conan-io/examples2.git
$ cd examples2/examples/tools/scm/git/capture_scm
在那里我们将找到一个小型“hello”项目,其中包含以下 conanfile.py
from conan import ConanFile
from conan.tools.cmake import CMake, cmake_layout
from conan.tools.scm import Git
class helloRecipe(ConanFile):
name = "hello"
version = "0.1"
# Binary configuration
settings = "os", "compiler", "build_type", "arch"
options = {"shared": [True, False], "fPIC": [True, False]}
default_options = {"shared": False, "fPIC": True}
generators = "CMakeDeps", "CMakeToolchain"
def export(self):
git = Git(self, self.recipe_folder)
# save the url and commit in conandata.yml
git.coordinates_to_conandata()
def source(self):
# we recover the saved url and commit from conandata.yml and use them to get sources
git = Git(self)
git.checkout_from_conandata_coordinates()
...
我们需要将此代码放入其自己的 Git 仓库中,以查看它在实际情况中如何工作,因此请在 examples2
仓库之外创建一个文件夹,并将当前文件夹的内容复制到那里,然后:
$ mkdir /home/myuser/myfolder # or equivalent in other OS
$ cp -R . /home/myuser/myfolder # or equivalent in other OS
$ cd /home/myuser/myfolder # or equivalent in other OS
# Initialize the git repo
$ git init .
$ git add .
$ git commit . -m wip
# Finally create the package
$ conan create .
...
======== Exporting recipe to the cache ========
hello/0.1: Exporting package recipe: /myfolder/conanfile.py
hello/0.1: Calling export()
hello/0.1: RUN: git status . --short --no-branch --untracked-files
hello/0.1: RUN: git rev-list HEAD -n 1 --full-history -- "."
hello/0.1: RUN: git remote -v
hello/0.1: RUN: git branch -r --contains cb7815a58529130b49da952362ce8b28117dee53
hello/0.1: RUN: git fetch origin --dry-run --depth=1 cb7815a58529130b49da952362ce8b28117dee53
hello/0.1: WARN: Current commit cb7815a58529130b49da952362ce8b28117dee53 doesn't exist in remote origin
This revision will not be buildable in other computer
hello/0.1: RUN: git rev-parse --show-toplevel
hello/0.1: Copied 1 '.py' file: conanfile.py
hello/0.1: Copied 1 '.yml' file: conandata.yml
hello/0.1: Exported to cache folder: /.conan2/p/hello237d6f9f65bba/e
...
======== Installing packages ========
hello/0.1: Calling source() in /.conan2/p/hello237d6f9f65bba/s
hello/0.1: Cloning git repo
hello/0.1: RUN: git clone "<hidden>" "."
hello/0.1: Checkout: cb7815a58529130b49da952362ce8b28117dee53
hello/0.1: RUN: git checkout cb7815a58529130b49da952362ce8b28117dee53
我们一步步解释发生了什么
当配方被导出到 Conan 缓存时,
export()
方法会执行git.coordinates_to_conandata()
,该方法通过内部调用git.get_url_and_commit()
将 Git URL 和提交存储在conandata.yml
文件中。有关这些方法的更多信息,请参阅Git 参考。这将获取指向本地
<local-path>/capture_scm
的仓库 URL 和提交8e8764c40bebabbe3ec57f9a0816a2c8e691f559
它会警告,一旦包上传到服务器并在其他计算机上尝试从源代码构建,此信息将不足以重新构建此配方,因为其他计算机上不包含
<local-path>/capture_scm
所指向的路径。这是预期的,因为我们创建的仓库没有定义任何远程仓库。如果我们的本地克隆定义了一个远程仓库,并且该远程仓库包含了我们正在构建的commit
,则scm_url
将指向远程仓库,从而使从源代码构建完全可复现。export()
方法将url
和commit
信息存储在conandata.yml
中,以实现未来的可复现性。当包需要从源代码构建并调用
source()
方法时,它会在git.checkout_from_conandata_coordinates()
方法内部从conandata.yml
文件中恢复信息,该方法会内部调用git.clone()
来检索源代码。在这种情况下,它将从<local-path>/capture_scm
中的本地检出克隆,但如果定义了远程仓库,它将从远程仓库克隆。
警告
为了实现可复现性,对于这种SCM 捕获技术而言,当前检出必须是干净的,这一点非常重要。如果它是脏的(未提交的更改),则无法保证构建的未来可复现性,因此 git.get_url_and_commit()
可能会引发错误,并要求提交更改。如果需要多次提交,建议在将更改推送到上游仓库之前,将这些提交进行 squash(压缩)。
如果我们现在执行第二次 conan create .
,由于仓库是脏的,我们将得到:
$ conan create .
hello/0.1: Calling export()
ERROR: hello/0.1: Error in export() method, line 19
scm_url, scm_commit = git.get_url_and_commit()
ConanException: Repo is dirty, cannot capture url and commit: .../capture_scm
这可以通过使用 git clean -xdf
清理仓库来解决,或者通过向仓库添加包含以下内容的 .gitignore
文件(这对于源代码控制来说无论如何都是一个好习惯):
test_package/build
test_package/CMakeUserPresets.json
坐标捕获使用 Git.get_url_and_commit()
方法,该方法默认执行以下操作:
如果仓库是脏的,它将引发异常
如果仓库不是脏的,但提交在远程仓库中不存在,它将发出警告,但会将本地文件夹作为仓库
url
返回。这样,无需将本地提交推送到服务器即可进行测试。core.scm:local_url=allow
可以抑制警告,而core.scm:local_url=block
将立即引发错误:最后一个值对于 CI 场景很有用,可以快速失败并节省一次可能在conan upload
中被阻止的构建。使用本地提交构建的包在尝试使用
conan upload
上传到服务器时将失败,因为这些本地提交不在服务器上,因此包可能无法复现。通过设置core.scm:local_url=allow
可以避免此上传错误。如果仓库不是脏的,并且提交存在于服务器中,它将返回远程 URL 和提交。
凭证管理¶
在上面的示例中,不需要凭证,因为我们的本地仓库不需要它们。但在实际场景中,可能需要凭证。
首先重要的一点是 git.get_url_and_commit()
将捕获 origin
远程仓库的 URL。出于多种原因,此 URL 不得编码令牌、用户或密码。首先,因为这将使过程不可重复,不同的构建、不同的用户将获得不同的 URL,从而导致不同的配方修订。此 url
应始终相同。推荐的方法是正交地管理凭证,例如使用 SSH 密钥。提供的示例包含一个执行此操作的 GitHub Action:
name: Build "hello" package capturing SCM in Github actions
run-name: ${{ github.actor }} checking hello-ci Git scm capture
on: [push]
jobs:
Build:
runs-on: ubuntu-latest
steps:
- name: Check out repository code
uses: actions/checkout@v3
with:
ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
- uses: actions/setup-python@v4
with:
python-version: '3.10'
- uses: webfactory/ssh-agent@v0.7.0
with:
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
- run: pip install conan
- run: conan profile detect
- run: conan create .
此 hello-demo.yml
负责以下事项:
检出
actions/checkout@v3
action 接收ssh-key
以git@
而非https
方式检出webfactory/ssh-agent@v0.7.0
action 确保 SSH 密钥在执行后续任务期间也被激活,而不仅仅是在检出期间。需要在 GitHub 界面中设置
SSH_PRIVATE_KEY
密钥,以及仓库的deploy key
(包含 SSH 密钥的私钥和公钥部分)
通过这种方式,可以将认证和凭证与配方功能完全分离,没有任何凭证泄露的风险。
注意
最佳实践
不要使用在 URL 中编码信息的认证机制。这有风险,很容易在日志中泄露凭证。建议使用 SSH 密钥等系统机制。
不建议在本地开发时执行
conan create
,而是运行conan install
并在本地构建,以避免过多不必要的提交。只有当所有内容都在本地正常工作时,才开始检查conan create
流程。