在包中处理源代码¶
在上一个教程章节中,我们为“Hello World”C++ 库创建了一个 Conan 包。我们使用 Conanfile 的exports_sources
属性来声明库源文件的位置。当源文件与 Conanfile 在同一文件夹中时,此方法是定义源文件位置的最简单方式。但是,有时源文件存储在存储库或远程服务器上的文件中,而不是与 Conanfile 位于同一位置。在本节中,我们将通过添加一个source()
方法来修改之前创建的配方,并解释如何
从存储在远程仓库中的 zip 文件检索源代码。
从 git 仓库的分支检索源代码。
请先克隆源代码以重新创建此项目。您可以在 GitHub 上的examples2 仓库中找到它们。
$ git clone https://github.com/conan-io/examples2.git
$ cd examples2/tutorial/creating_packages/handle_sources
项目的结构与上一个示例相同,但没有库源代码
.
├── CMakeLists.txt
├── conanfile.py
└── test_package
├── CMakeLists.txt
├── conanfile.py
└── src
└── example.cpp
从存储在远程仓库中的 zip 文件获取源代码¶
让我们看看 conanfile.py 中的变化
from conan import ConanFile
from conan.tools.cmake import CMakeToolchain, CMake, cmake_layout
from conan.tools.files import get
class helloRecipe(ConanFile):
name = "hello"
version = "1.0"
...
# Binary configuration
settings = "os", "compiler", "build_type", "arch"
options = {"shared": [True, False], "fPIC": [True, False]}
default_options = {"shared": False, "fPIC": True}
def source(self):
# Please, be aware that using the head of the branch instead of an immutable tag
# or commit is a bad practice and not allowed by Conan
get(self, "https://github.com/conan-io/libhello/archive/refs/heads/main.zip",
strip_root=True)
def config_options(self):
if self.settings.os == "Windows":
del self.options.fPIC
def layout(self):
cmake_layout(self)
def generate(self):
tc = CMakeToolchain(self)
tc.generate()
def build(self):
cmake = CMake(self)
cmake.configure()
cmake.build()
def package(self):
cmake = CMake(self)
cmake.install()
def package_info(self):
self.cpp_info.libs = ["hello"]
如您所见,配方是相同的,但我们没有像以前那样声明exports_sources
属性,即
exports_sources = "CMakeLists.txt", "src/*", "include/*"
我们使用此信息声明了一个source()
方法
def source(self):
# Please, be aware that using the head of the branch instead of an immutable tag
# or commit is strongly discouraged, unsupported by Conan and likely to cause issues
get(self, "https://github.com/conan-io/libhello/archive/refs/heads/main.zip",
strip_root=True)
我们使用了conan.tools.files.get()工具,该工具将首先**下载**我们作为参数传入的 URL 中的 zip 文件,然后**解压**它。请注意,我们传入了strip_root=True
参数,以便如果所有解压后的内容都在一个单独的文件夹中,所有内容都会被移动到父文件夹中(有关详细信息,请查看conan.tools.files.unzip()参考资料)。
警告
期望将来检索源代码会产生相同的结果。强烈不鼓励并**不支持**使用可变源,例如 git 中的移动引用(例如 HEAD 分支),或内容可能随时间变化的文件 URL。不遵循此做法将导致未定义行为,可能导致损坏。
zip 文件的内容与我们之前在 Conan 配方旁边的源代码相同,因此如果您执行conan create,结果将与之前相同。
$ conan create .
...
-------- Installing packages ----------
Installing (downloading, building) binaries...
hello/1.0: Calling source() in /Users/user/.conan2/p/0fcb5ffd11025446/s/.
Downloading update_source.zip
hello/1.0: Unzipping 3.7KB
Unzipping 100 %
hello/1.0: Copying sources to build folder
hello/1.0: Building your package in /Users/user/.conan2/p/tmp/369786d0fb355069/b
...
-------- Testing the package: Running test() ----------
hello/1.0 (test package): Running test()
hello/1.0 (test package): RUN: ./example
hello/1.0: Hello World Release!
hello/1.0: __x86_64__ defined
hello/1.0: __cplusplus199711
hello/1.0: __GNUC__4
hello/1.0: __GNUC_MINOR__2
hello/1.0: __clang_major__13
hello/1.0: __clang_minor__1
hello/1.0: __apple_build_version__13160021
请检查突出显示的关于下载和解压操作消息的行。
从 git 仓库的分支获取源代码¶
现在,让我们修改source()
方法,从 git 仓库而不是 zip 文件中获取源代码。我们只展示相关部分
...
from conan.tools.scm import Git
class helloRecipe(ConanFile):
name = "hello"
version = "1.0"
...
def source(self):
git = Git(self)
git.clone(url="https://github.com/conan-io/libhello.git", target=".")
...
在这里,我们使用conan.tools.scm.Git()工具。Git
类实现了多个与 git 仓库协同工作的方法。在这种情况下,我们调用clone()
方法,将 https://github.com/conan-io/libhello.git 仓库克隆到默认分支,并使用相同的文件夹来克隆源代码而不是子文件夹(传入target="."
参数)。
警告
如上所述,这只是一个简单的示例。Git()
的源也必须是不可变的。为了保证正确行为,有必要检出不可变的标签或特定的提交。不允许使用仓库的 HEAD,否则可能导致未定义行为和损坏。
要在仓库中检出提交或标签,我们使用 Git 工具的checkout()
方法
def source(self):
git = Git(self)
git.clone(url="https://github.com/conan-io/libhello.git", target=".")
git.checkout("<tag> or <commit hash>")
有关Git
类方法的更多信息,请查看conan.tools.scm.Git()参考资料。
请注意,也可以通过调用self.run()
方法来运行其他命令。
使用 conandata.yml 文件¶
我们可以在与conanfile.py
相同的文件夹中创建一个名为conandata.yml
的文件。该文件将由 Conan 自动导出和解析,我们可以从配方中读取这些信息。这很方便,例如,用于提取外部源代码仓库、zip 文件等的 URL。这是一个conandata.yml
的示例
sources:
"1.0":
url: "https://github.com/conan-io/libhello/archive/refs/heads/main.zip"
sha256: "7bc71c682895758a996ccf33b70b91611f51252832b01ef3b4675371510ee466"
strip_root: true
"1.1":
url: ...
sha256: ...
配方不需要为代码的每个版本进行修改。我们可以将指定版本的所有keys
(url
、sha256
和strip_root
)作为参数传递给get
函数,在这种情况下,这允许我们验证下载的 zip 文件是否具有正确的sha256
。因此,我们可以将 source 方法修改为这样
def source(self):
get(self, **self.conan_data["sources"][self.version])
# Equivalent to:
# data = self.conan_data["sources"][self.version]
# get(self, data["url"], sha256=data["sha256"], strip_root=data["strip_root"])
适用于当前版本的conandata.yml
信息也以序列化配方信息的格式提供,请参阅图信息 JSON 格式
另请参阅
捕获 Git SCM 源代码信息而不是使用
exports_sources
复制源代码。