管理包元数据文件¶
警告
此功能处于实验阶段,可能会发生重大更改。有关更多信息,请参阅Conan 稳定性部分。
Conan 包通常由多个 C 和 C++ 工件、头文件、编译库和可执行文件组成。但有些文件可能对于此类包的正常使用不是必需的,但出于合规性、技术或业务原因,这些文件可能非常重要,例如:
完整的构建日志
测试可执行文件
运行测试套件的测试结果
调试工件,如大型 .pdb 文件
覆盖率、消毒器或其他源代码或二进制分析工具的结果
有关构建、确切机器、环境、作者、CI 数据的上下文和元数据
其他合规性和安全相关文件
存储和跟踪这些文件有几个重要原因,例如法规、合规性、安全性、可重现性和可追溯性。这些文件的问题在于它们可能很大/很重,如果我们将它们存储在包内(只需在package()
方法中复制工件),这将使包变得更大,并且会影响下载、解压和使用包的速度。这种情况通常会发生多次,无论是在开发人员机器上还是在 CI 中,这都可能对开发人员体验和基础设施成本产生影响。此外,包是不可变的,也就是说,一旦包被创建,就不应修改。如果我们在包创建后,甚至在包上传后,想要添加额外的元数据文件,这可能是一个问题。
元数据文件功能允许以集成统一的方式创建、上传、附加和存储与包相关的元数据,同时避免对开发人员和 CI 速度及成本的影响,因为元数据文件在使用包时默认不会被下载和解压。
值得强调的是,元数据有两种类型
配方元数据,与
conanfile.py
配方相关联,元数据应是该配方创建的所有二进制文件(包名称、版本和配方修订版)通用的。这种元数据可能不太常见,但例如,源代码扫描的一些结果(对所有配置和构建都通用)可以是配方元数据。包二进制元数据,与给定特定配置的包二进制文件相关联,并由
package_id
表示。特定于二进制配置的构建日志、测试报告等将是包元数据。
在配方中创建元数据¶
配方可以直接在其方法中定义元数据。一个常见的用例是存储日志。使用self.recipe_metadata_folder
和self.package_metadata_folder
,配方可以在这些位置存储文件。
import os
from conan import ConanFile
from conan.tools.files import save, copy
class Pkg(ConanFile):
name = "pkg"
version = "0.1"
def layout(self):
# Or something else, like the "cmake_layout(self)" built-in layout
self.folders.build = "mybuild"
self.folders.generators = "mybuild/generators"
def export(self):
# logs that might be generated in the recipe folder at "export" time.
# these would be associated with the recipe repo and original source of the recipe repo
copy(self, "*.log", src=self.recipe_folder,
dst=os.path.join(self.recipe_metadata_folder, "logs"))
def source(self):
# logs originated in the source() step, for example downloading files, patches or other stuff
save(self, os.path.join(self.recipe_metadata_folder, "logs", "src.log"), "srclog!!")
def build(self):
# logs originated at build() step, the most common ones
save(self, "mylogs.txt", "some logs!!!")
copy(self, "mylogs.txt", src=self.build_folder,
dst=os.path.join(self.package_metadata_folder, "logs"))
请注意,“配方”方法(对所有二进制文件通用的方法,例如export()
和source()
)应使用self.recipe_metadata_folder
,而“包”特定方法(build()
、package()
)应使用self.package_metadata_folder
。
对此配方执行conan create
命令,将在 Conan 缓存中创建“元数据”文件夹。我们可以使用以下命令查看这些文件夹:
$ conan create .
$ conan cache path pkg/0.1 --folder=metadata
# folder containing the recipe metadata
$ conan cache path pkg/0.1:package_id --folder=metadata
# folder containing the specific "package_id" binary metadata
也可以使用“本地流”命令并获取本地“元数据”文件夹。如果我们要这样做,强烈建议使用像上面那样的layout()
方法,以避免弄乱当前文件夹。然后,本地命令将允许测试和调试功能。
$ conan source .
# check local metadata/logs/src.log file
$ conan build .
# check local mybuild/metadata/logs/mylogs.txt file
注意:请注意,本地创建的元数据在执行conan export-pkg
命令期间不会导出到 Conan 缓存。一些元数据,例如在export()
方法中生成的元数据,可以在缓存中生成,因为conan export-pkg
命令会调用该方法,但“build”文件夹内的元数据将不会导出。如果您想将该元数据添加到导出的包中,您可以在执行conan export-pkg
之后,使用conan cache path
报告的路径进行复制,如下面“使用命令添加元数据”部分所述。
使用钩子创建元数据¶
如果配方之间存在一些共同的元数据,可以使用钩子在不修改配方的情况下捕获它。假设我们有一个更简单的配方:
import os
from conan import ConanFile
from conan.tools.files import save, copy
class Pkg(ConanFile):
name = "pkg"
version = "0.1"
no_copy_source = True
def layout(self):
self.folders.build = "mybuild"
self.folders.generators = "mybuild/generators"
def source(self):
save(self, "logs/src.log", "srclog!!")
def build(self):
save(self, "logs/mylogs.txt", "some logs!!!")
如我们所见,这根本没有使用元数据文件夹。现在让我们定义以下钩子:
import os
from conan.tools.files import copy
def post_export(conanfile):
conanfile.output.info("post_export")
copy(conanfile, "*.log", src=conanfile.recipe_folder,
dst=os.path.join(conanfile.recipe_metadata_folder, "logs"))
def post_source(conanfile):
conanfile.output.info("post_source")
copy(conanfile, "*", src=os.path.join(conanfile.source_folder, "logs"),
dst=os.path.join(conanfile.recipe_metadata_folder, "logs"))
def post_build(conanfile):
conanfile.output.info("post_build")
copy(conanfile, "*", src=os.path.join(conanfile.build_folder, "logs"),
dst=os.path.join(conanfile.package_metadata_folder, "logs"))
使用这些钩子将产生与配方内方法非常相似的效果:当conan create
执行时,元数据文件将在缓存中创建,并且对于conan source
和conan build
本地流程也会在本地创建。
使用命令添加元数据¶
元数据文件可以在包创建后添加或修改。为此,使用conan cache path
命令将返回进行该操作的文件夹,因此在该位置复制、创建或修改文件即可实现此目的。
$ conan create . --name=pkg --version=0.1
$ conan cache path pkg/0.1 --folder=metadata
# folder to put the metadata, initially empty if we didn't use hooks
# and the recipe didn't store any metadata. We can copy and put files
# in the folder
$ conan cache path pkg/0.1:package_id --folder=metadata
# same as above, for the package metadata, we can copy and put files in
# the returned folder
此元数据是本地添加的,在 Conan 缓存中。如果您想更新服务器元数据,则需要从缓存上传。
上传元数据¶
到目前为止,元数据已在本地创建并存储在 Conan 缓存中。将元数据上传到服务器已与现有的conan upload
命令集成。
$ conan upload "*" -c -r=default
# Uploads recipes, packages and metadata to the "default" remote
...
pkg/0.1: Recipe metadata: 1 files
pkg/0.1:da39a3ee5e6b4b0d3255bfef95601890afd80709: Package metadata: 1 files
默认情况下,当配方或包上传到服务器时,conan upload
将上传配方和包的元数据。但有些情况下 Conan 会完全避免此次上传,如果它检测到服务器上已存在修订版,它将不会上传配方或包。如果元数据已在本地修改或添加了新文件,我们可以使用以下命令强制上传:
# We added some metadata to the packages in the cache
# But those packages already exist in the server
$ conan upload "*" -c -r=default --metadata="*"
...
pkg/0.1: Recipe metadata: 1 files
pkg/0.1:da39a3ee5e6b4b0d3255bfef95601890afd80709: Package metadata: 1 files
--metadata
参数允许指定我们要上传的元数据文件。如果我们将它们组织成文件夹,我们可以指定--metadata="logs*"
来仅上传日志元数据,而不上传其他可能的元数据,例如test
元数据。
# Upload only the logs metadata of the zlib/1.2.13 binaries
# This will upload the logs even if zlib/1.2.13 is already in the server
$ conan upload "zlib/1.2.13:*" -r=remote -c --metadata="logs/*"
# Multiple patterns are allowed:
$ conan upload "*" -r=remote -c --metadata="logs/*" --metadata="tests/*"
有时,即使元数据缓存文件夹包含文件,上传包而不上传元数据也可能很有用。要忽略上传元数据,请使用空参数作为元数据模式:
# Upload only the packages, not the metadata
$ conan upload "*" -r=remote -c --metadata=""
混合使用--metadata=""
和--metadata="*"
是禁止的,并且会引发错误。
# Invalid command, it will raise an error
$ conan upload "*" -r=remote -c --metadata="" --metadata="logs/*"
ERROR: Empty string and patterns can not be mixed for metadata.
下载元数据¶
如上所述,元数据默认不下载。当使用conan install
或conan create
从服务器获取依赖项时下载包,这些服务器上的元数据将不会被下载。
从服务器恢复元数据的方法是使用conan download
命令明确指定:
# Get the metadata of the "pkg/0.1" package
$ conan download pkg/0.1 -r=default --metadata="*"
...
$ conan cache path pkg/0.1 --folder=metadata
# Inspect the recipe metadata in the returned folder
$ conan cache path pkg/0.1:package_id --folder=metadata
# Inspect the package metadata for binary "package_id"
元数据的检索是按包使用download
完成的。如果我们要下载整个依赖图的元数据,则需要使用“包列表”。
$ conan install . --format=json -r=remote > graph.json
$ conan list --graph=graph.json --format=json > pkglist.json
# the list will contain the "remote" origin of downloaded packages
$ conan download --list=pkglist.json --metadata="*" -r=remote
请注意,“包列表”将只包含与“远程”来源关联的已下载包。如果它们之前已在缓存中,则它们将不会列在“远程”来源下,元数据也不会被下载。如果您想收集依赖项元数据,请记住在从服务器安装包时下载它。还有其他可能性,例如可以自动从服务器收集和下载依赖项元数据的自定义命令。
删除元数据¶
目前无法使用 Conan 从服务器端删除元数据,因为元数据是“附加的”,可以添加新数据,但不能删除(否则将无法在不先下载所有先前元数据的情况下添加新元数据,这可能效率很低,且更容易出错,尤其对可能的竞态条件敏感)。
从服务器端删除元数据的建议是使用服务器可能提供的工具、Web 界面或 API。
注意
最佳实践
元数据对于使用包来说不应该是必需的。在不下载其元数据的情况下使用配方和包应该是可能的。如果元数据对于包的使用是强制性的,那么它就不是元数据,而应该作为头文件和二进制文件打包。
元数据读取访问不应是频繁的操作,也不是开发人员必须执行的操作。元数据读取旨在用于特殊情况,例如出于合规性需要恢复某些构建日志,或者调试或重新检查崩溃时可能需要某些测试可执行文件。
Conan 不会对元数据文件进行任何压缩或解压缩。如果元数据文件很多,请考虑自行压缩它们,否则上传大量文件可能会花费很长时间。如果您需要处理不同类型的元数据(日志、测试、报告),将每个类别下的文件打包可能会更好,以便能够使用
--metadata=xxx
参数进行过滤。
将 test_package 作为元数据¶
这是一个元数据用法的示例,将完整的test_package
文件夹存储为元数据,以便稍后恢复和执行。请注意,这不一定适用于生产环境。
让我们从一个钩子开始,它会自动将test_package
文件夹存储为配方元数据。
import os
from conan.tools.files import copy
def post_export(conanfile):
conanfile.output.info("Storing test_package")
folder = os.path.join(conanfile.recipe_folder, "test_package")
copy(conanfile, "*", src=folder,
dst=os.path.join(conanfile.recipe_metadata_folder, "test_package"))
请注意,这个钩子没有考虑到test_package
可能会因大量临时构建对象而变得杂乱(在添加到元数据之前应先清理),并且它也没有检查test_package
是否可能根本不存在并导致崩溃。
当包被创建并上传时,它会将包含test_package
的配方元数据上传到服务器。
$ conan create ...
$ conan upload "*" -c -r=default # uploads metadata
...
pkg/0.1: Recipe metadata: 1 files
让我们删除本地副本,并假设包已安装,但元数据未安装。
$ conan remove "*" -c # lets remove the local packages
$ conan install --requires=pkg/0.1 -r=default # this will not download metadata
如果在此阶段安装的包在我们的应用程序中出现故障,我们可以恢复test_package
,下载它,并将其复制到我们当前的文件夹。
$ conan download pkg/0.1 -r=default --metadata="test_package*"
$ conan cache path pkg/0.1 --folder=metadata
# copy the test_package folder from the cache, to the current folder
# like `cp -R ...`
# Execute the test_package
$ conan test metadata/test_package pkg/0.1
pkg/0.1 (test package): Running test()
另请参阅
待办:如何使用自定义部署器或命令收集完整依赖图元数据的示例
这是一项实验性功能。我们期待您的反馈、用例和需求,以不断改进此功能。请在Github issues中报告。