修订¶
本节介绍如何在不显式创建新版本的情况下,对给定配方或源代码进行修改时,仍然通过一种称为修订的机制在内部跟踪这些更改。
创建不同的修订¶
让我们从一个基本的“hello”包开始
$ mkdir hello && cd hello
$ conan remove hello* -c # clean possible existing ones
$ conan new cmake_lib -d name=hello -d version=1.0
$ conan create .
hello/1.0: Hello World Release!
...
我们现在可以列出缓存中现有的配方修订
$ conan list "hello/1.0#*"
Local Cache
hello
hello/1.0
revisions
2475ece651f666f42c155623228c75d2 (2023-01-31 23:08:08 UTC)
如果现在我们编辑 src/hello.cpp
文件,将输出消息从“Hello”更改为“Bye”
void hello(){
#ifdef NDEBUG
std::cout << "hello/1.0: Bye World Release!\n";
...
因此,如果我们再次创建包,而不更改版本 hello/1.0
,我们将得到一个新的输出
$ conan create .
hello/1.0: Bye World Release!
...
但即使版本相同,内部也已创建了一个新修订 2b547b7f20f5541c16d0b5cbcf207502
。
$ conan list "hello/1.0#*"
Local Cache
hello
hello/1.0
revisions
2475ece651f666f42c155623228c75d2 (2023-01-31 23:08:08 UTC)
2b547b7f20f5541c16d0b5cbcf207502 (2023-01-31 23:08:25 UTC)
此配方修订是配方内容的哈希值,包括 conanfile.py
和导出的源文件(src/main.cpp
、CMakeLists.txt
等,即配方中导出的所有文件)。
我们现在可以编辑 conanfile.py
,定义 license
值
class helloRecipe(ConanFile):
name = "hello"
version = "1.0"
# Optional metadata
license = "MIT"
...
因此,如果我们再次创建包,输出将相同,但我们也将得到一个新的修订,因为 conanfile.py
发生了更改
$ conan create .
hello/1.0: Bye World Release!
...
$ conan list "hello/1.0#*"
Local Cache
hello
hello/1.0
revisions
2475ece651f666f42c155623228c75d2 (2023-01-31 23:08:08 UTC)
2b547b7f20f5541c16d0b5cbcf207502 (2023-01-31 23:08:25 UTC)
1d674b4349d2b1ea06aa6419f5f99dd9 (2023-01-31 23:08:34 UTC)
重要
配方修订是内容的哈希值。它可以通过 revision_mode = "scm"
更改为 Git 提交哈希值。但无论如何,关键是每个修订都代表一个不可变源,包括配方和源代码
如果源文件由
exports_sources
管理,那么它们将自动成为哈希的一部分如果源文件是从外部位置(如下载的 tarball 或 git clone)检索的,则应通过强制检出唯一的不可变标签或提交来保证唯一性。移动目标(如分支名称或 HEAD)将被破坏,因为修订被认为是不可变的。
源代码或配方中的任何更改都应始终意味着一个新的修订。
警告
行尾问题
默认情况下,Git 会在 Windows 系统上检出文件时使用 CRLF
行尾。这导致与使用 LF
行尾的 Linux 系统上的文件不同。由于文件不同,在 Windows 上计算的 Conan 配方修订将与 Linux 等其他平台上的修订不同。有关此问题以及如何解决此问题的更多信息,请查看 FAQ 专用部分。
使用修订¶
默认情况下,配方修订解析为每个给定版本的最新修订。在上面的示例中,我们可以有一个 chat/1.0
包,它使用上述 hello/1.0
包
$ cd ..
$ mkdir chat && cd chat
$ conan new cmake_lib -d name=chat -d version=1.0 -d requires=hello/1.0
$ conan create .
...
Requirements
chat/1.0#17b45a168519b8e0ed178d822b7ad8c8 - Cache
hello/1.0#1d674b4349d2b1ea06aa6419f5f99dd9 - Cache
...
hello/1.0: Bye World Release!
chat/1.0: Hello World Release!
我们可以看到,默认情况下,它解析为最新的修订 1d674b4349d2b1ea06aa6419f5f99dd9
,因此我们也看到了 hello/1.0: Bye World
修改后的消息。
可以在配方中明确依赖给定修订,因此可以修改 chat/1.0
配方以定义它需要第一个创建的修订
def requirements(self):
self.requires("hello/1.0#2475ece651f666f42c155623228c75d2")
因此,创建 chat
现在将强制使用第一个修订
$ conan create .
...
Requirements
chat/1.0#12f87e1b8a881da6b19cc7f229e16c76 - Cache
hello/1.0#2475ece651f666f42c155623228c75d2 - Cache
...
hello/1.0: Hello World Release!
chat/1.0: Hello World Release!
上传修订¶
默认情况下,上传命令只上传最新修订
# upload latest revision only, all package binaries
$ conan upload hello/1.0 -c -r=myremote
如果由于某种原因我们想上传所有现有修订,可以使用
# upload all revisions, all binaries for each revision
$ conan upload hello/1.0#* -c -r=myremote
在服务器端,最新上传的修订成为最新修订,并且是默认解析的修订。因此,上述命令按顺序(从旧修订到最新修订)上传不同的修订,以便在服务器端保持修订的相对顺序。
请注意,如果另一台机器决定上传某个很久以前创建的修订,它仍将成为服务器上的最新修订,因为它是在服务器端以该时间创建的。
包修订¶
创建的二进制包也会计算其内容的哈希值,形成包修订。但它们与配方修订的性质非常不同。配方修订是自然预期的,源代码或配方中的每次更改都会导致一个新的配方修订。但是二进制包不应该有多个包修订,因为二进制包的可变性已经编码在唯一的 package_id
中。换句话说,如果配方修订相同(配方和源代码输入完全相同)并且 package_id
相同(配置配置文件、设置等完全相同),那么该二进制包应该只构建一次。
由于 C 和 C++ 构建不是确定性的,因此在不修改任何内容的情况下,同一包的后续构建可能会创建新的包修订
# Build again 2 times the latest
$ conan create .
$ conan create .
在某些操作系统(如 Windows)中,此构建不可复现,并且生成的工件将具有不同的校验和,从而导致新的包修订
$ conan list "hello/1.0:*#*"
Local Cache
hello
hello/1.0
revisions
1d674b4349d2b1ea06aa6419f5f99dd9 (2023-02-01 00:03:29 UTC)
packages
2401fa1d188d289bb25c37cfa3317e13e377a351
revisions
8b8c3deef5ef47a8009d4afaebfe952e (2023-01-31 23:08:40 UTC)
8e8d380347e6d067240c4c00132d42b1 (2023-02-01 00:03:12 UTC)
c347faaedc1e7e3282d3bfed31700019 (2023-02-01 00:03:35 UTC)
info
settings
arch: x86_64
build_type: Release
...
默认情况下,包修订也将解析为最新的。但是,无法在配方中明确固定包修订,配方只能要求到上面定义的配方修订。
警告
最佳实践
对于任何给定的配方修订 + package_id
,存在超过 1 个包修订是一种警示或潜在的不良实践。这意味着在不需要时重新构建了某些内容,浪费了计算和存储资源。有多种方法可以避免这种情况,例如 conan create . --build=missing:hello*
将仅在不存在时构建该二进制包(或者运行 conan graph info
也可以返回需要构建的信息)。