锁定文件¶
锁定文件是一种机制,即使创建了依赖项的新版本或修订版,也能实现可复现的依赖项。让我们通过一个实际的例子来看看,首先克隆 examples2 仓库
$ git clone https://github.com/conan-io/examples2.git
$ cd examples2/tutorial/versioning/lockfiles/intro
在这个文件夹中,我们有一个小型项目,由 3 个包组成:一个模拟数学库的 matrix
包,一个模拟游戏引擎的 engine
包,以及一个模拟某些 32 位系统声音库的 sound32
包。这些包实际上大部分是空的,它们不构建任何代码,但它们很适合学习锁定文件的概念。
我们将从创建第一个 matrix/1.0
版本开始
$ conan create matrix --version=1.0
现在我们可以在 engine
文件夹中查看其配方
class Engine(ConanFile):
name = "engine"
settings = "arch"
def requirements(self):
self.requires("matrix/[>=1.0 <2.0]")
if self.settings.arch == "x86":
self.requires("sound32/[>=1.0 <2.0]")
让我们进入 engine
文件夹并安装其依赖项
$ cd engine
$ conan install .
...
Requirements
matrix/1.0#905c3f0babc520684c84127378fefdd0 - Cache
Resolved version ranges
matrix/[>=1.0 <2.0]: matrix/1.0
由于 matrix/1.0
版本在有效范围内,它被解析并使用。但如果有人创建了新的 matrix/1.1
或 1.X
版本,它也会被自动使用,因为它也在有效范围内。为了避免这种情况,我们将通过创建 conan.lock
锁定文件来捕获当前依赖项的“快照”
$ conan lock create .
$ cat conan.lock
{
"version": "0.5",
"requires": [
"matrix/1.0#905c3f0babc520684c84127378fefdd0%1675278126.0552447"
],
"build_requires": [],
"python_requires": []
}
我们可以看到创建的 conan.lock
锁定文件包含了 matrix/1.0
版本及其修订版。但是 sound32/1.0
不在锁定文件中,因为对于默认配置(非 x86
),sound32
不是一个依赖项。
现在,一个新的 matrix/1.1
版本被创建
$ cd ..
$ conan create matrix --version=1.1
$ cd engine
然后看看当我们为引擎发出新的 conan install
命令时会发生什么
$ conan install .
# equivalent to conan install . --lockfile=conan.lock
...
Requirements
matrix/1.0#905c3f0babc520684c84127378fefdd0 - Cache
正如我们所见,新的 matrix/1.1
没有被使用,即使它在有效范围内!发生这种情况是因为如果找到 conan.lock
文件,默认情况下会使用 --lockfile=conan.lock
。锁定的 matrix/1.0
版本和修订版将用于解析范围,而 matrix/1.1
将被忽略。
同样,可以发出其他 Conan 命令,如果 conan.lock
存在,它将被使用
$ conan graph info . --filter=requires # --lockfile=conan.lock is implicit
# display info for matrix/1.0
$ conan create . --version=1.0 # --lockfile=conan.lock is implicit
# creates the engine/1.0 package, using matrix/1.0 as dependency
如果打算使用锁定文件(例如在 CI 中),最好明确指定参数 --lockfile=conan.lock
。
多配置锁定文件¶
我们上面看到,engine
对 sound32
包有一个条件依赖项,条件是架构为 x86
。这也意味着上面创建的锁定文件中没有捕获 sound32
包的版本。
让我们先创建 sound32/1.0
包,然后尝试安装 engine
$ cd ..
$ conan create sound32 --version=1.0
$ cd engine
$ conan install . -s arch=x86 # FAILS!
ERROR: Requirement 'sound32/[>=1.0 <2.0]' not in lockfile
发生这种情况是因为 conan.lock
锁定文件不包含 sound32
的锁定版本。默认情况下,锁定文件是严格的,如果我们要锁定依赖项,则必须在锁定文件中找到匹配的版本。我们可以通过 --lockfile-partial
参数来放宽此假设
$ conan install . -s arch=x86 --lockfile-partial
...
Requirements
matrix/1.0#905c3f0babc520684c84127378fefdd0 - Cache
sound32/1.0#83d4b7bf607b3b60a6546f8b58b5cdd7 - Cache
Resolved version ranges
sound32/[>=1.0 <2.0]: sound32/1.0
这将能够部分锁定到 matrix/1.0
,并像往常一样解析 sound32
版本范围。但我们可以做得更好,我们可以扩展我们的锁定文件,也锁定 sound32/1.0
版本,以避免新 sound32
意外版本可能造成的干扰
$ conan lock create . -s arch=x86
$ cat conan.lock
{
"version": "0.5",
"requires": [
"sound32/1.0#83d4b7bf607b3b60a6546f8b58b5cdd7%1675278904.0791488",
"matrix/1.0#905c3f0babc520684c84127378fefdd0%1675278900.0103245"
],
"build_requires": [],
"python_requires": []
}
现在,matrix/1.0
和 sound32/1.0
都已锁定在我们的 conan.lock
锁定文件中。可以将此锁定文件用于两种配置(64 位和 x86 架构),锁定文件中包含给定配置未使用的版本不是问题,只要该配置所需的依赖项在其中找到匹配的版本即可。
重要
锁定文件包含按版本和修订版本排序的需求列表,因此最新版本和修订版本在解析锁定文件时会优先考虑。一个锁定文件可以包含同一包的两个或多个不同版本,仅仅是因为不同的版本范围需要它们。排序将提供正确的逻辑,以便每个范围解析为每个有效版本。
如果锁定文件中的版本不符合有效范围,则不会使用它。锁定文件不可能强制一个与 conanfile
所需定义相悖的依赖项,因为它们是现有/可实现的依赖关系图的“快照”,但不能定义“不可能”的依赖关系图。
演进锁定文件¶
即使锁定文件强制并限制了可为图解析的版本,这并不意味着锁定文件不能演进。实际上,锁定文件的受控演进对于持续集成等重要过程至关重要,因为在这种情况下,需要独立于其他可能的并发更改来测试图中一个更改的影响。
在本节中,我们将介绍允许这种演进的锁定文件的一些基本功能。
首先,如果现在我们想在我们的 engine
中引入并测试新的 matrix/1.1
版本,而无需拉取许多可能也获得新版本的其他依赖项,我们可以手动将 matrix/1.1
添加到锁定文件
$ Running: conan lock add --requires=matrix/1.1
$ cat conan.lock
{
"version": "0.5",
"requires": [
"sound32/1.0#83d4b7bf607b3b60a6546f8b58b5cdd7%1675278904.0791488",
"matrix/1.1",
"matrix/1.0#905c3f0babc520684c84127378fefdd0%1675278900.0103245"
],
"build_requires": [],
"python_requires": []
}
需要明确的是:手动使用 conan lock add
添加不一定是推荐的流程,可以通过其他方法自动化此任务,这些方法将在后面解释。这只是对原理和概念的介绍。
重要的思想是,现在我们的锁定文件中有了 matrix
的 2 个版本,并且 matrix/1.1
在 matrix/1.0
之前,所以对于范围 matrix/[>=1.0 <2.0]
,第一个(matrix/1.1
)将被优先考虑。这意味着当现在使用新的锁定文件时,它将解析到 matrix/1.1
版本(即使系统中存在 matrix/1.2
或更高版本)
$ conan install . -s arch=x86 --lockfile-out=conan.lock
Requirements
matrix/1.1#905c3f0babc520684c84127378fefdd0 - Cache
sound32/1.0#83d4b7bf607b3b60a6546f8b58b5cdd7 - Cache
$ cat conan.lock
{
"version": "0.5",
"requires": [
"sound32/1.0#83d4b7bf607b3b60a6546f8b58b5cdd7%1675278904.0791488",
"matrix/1.1#905c3f0babc520684c84127378fefdd0%1675278901.7527816",
"matrix/1.0#905c3f0babc520684c84127378fefdd0%1675278900.0103245"
],
"build_requires": [],
"python_requires": []
}
请注意,现在 matrix/1.1
已被解析,并且其 revision
也存储在锁定文件中(因为 --lockfile-out=conan.lock
作为参数传递)。
诚然,之前的 matrix/1.0
版本没有被使用。如上所述,锁定文件中存在未使用的旧版本是无害的。但是,如果我们要修剪未使用的版本和修订,我们可以为此目的使用 --lockfile-clean
$ conan install . -s arch=x86 --lockfile-out=conan.lock --lockfile-clean
...
Requirements
matrix/1.1#905c3f0babc520684c84127378fefdd0 - Cache
sound32/1.0#83d4b7bf607b3b60a6546f8b58b5cdd7 - Cache
...
$ cat conan.lock
{
"version": "0.5",
"requires": [
"sound32/1.0#83d4b7bf607b3b60a6546f8b58b5cdd7%1675278904.0791488",
"matrix/1.1#905c3f0babc520684c84127378fefdd0%1675278901.7527816"
],
"build_requires": [],
"python_requires": []
}
值得注意的是,-lockfile-clean
可能会删除给定配置中锁定的版本。例如,如果使用 x86_64
架构而不是上述情况,--lockfile-clean
将修剪“未使用”的 sound32
,因为在该配置中它没有被使用。可以为每个不同的配置评估新的锁定文件,然后合并它们
$ conan lock create . --lockfile-out=64.lock --lockfile-clean
$ conan lock create . -s arch=x86 --lockfile-out=32.lock --lockfile-clean
$ cat 64.lock
{
"version": "0.5",
"requires": [
"matrix/1.1#905c3f0babc520684c84127378fefdd0%1675294635.6049662"
],
"build_requires": [],
"python_requires": []
}
$ cat 32.lock
{
"version": "0.5",
"requires": [
"sound32/1.0#83d4b7bf607b3b60a6546f8b58b5cdd7%1675294637.9775107",
"matrix/1.1#905c3f0babc520684c84127378fefdd0%1675294635.6049662"
],
"build_requires": [],
"python_requires": []
}
$ conan lock merge --lockfile=32.lock --lockfile=64.lock --lockfile-out=conan.lock
$ cat conan.lock
{
"version": "0.5",
"requires": [
"sound32/1.0#83d4b7bf607b3b60a6546f8b58b5cdd7%1675294637.9775107",
"matrix/1.1#905c3f0babc520684c84127378fefdd0%1675294635.6049662"
],
"build_requires": [],
"python_requires": []
}
这种多清理 + 合并操作不是开发人员应该做的事情,只有 CI 脚本,以及一些将在以后解释的高级 CI 流程才会这样做。
另请参阅