set_version()¶
动态定义 version
属性。当同一个配方用于创建同一包的不同版本,并且该版本是在其他地方(如 Git 分支、文本文件或构建脚本文件)定义时,可能需要此方法。这是一种常见情况。
此方法仅在配方导出到缓存(使用 conan create
和 conan export
命令)以及配方在本地使用(例如使用 conan install .
命令)时执行。在所有其他情况下,包的版本已完全定义,并且不会调用 set_version()
,因此请勿依赖它来实现除定义 self.version
值以外的任何功能。
如果当前包版本是在 version.txt 文件中定义的,则可以这样操作:
from conan import ConanFile
from conan.tools.files import load
class Pkg(ConanFile):
def set_version(self):
# This will execute relatively to the current user directory (version.txt in cwd)
self.version = load(self, "version.txt")
# if "version.txt" is located relative to the conanfile.py better do:
self.version = load(self, os.path.join(self.recipe_folder, "version.txt"))
包版本也可以通过命令行参数 --version=xxxx
为某些命令定义。如果我们要优先使用命令行参数,则应该这样做:
from conan import ConanFile
from conan.tools.files import load
class Pkg(ConanFile):
def set_version(self):
# Command line ``--version=xxxx`` will be assigned first to self.version and have priority
self.version = self.version or load(self, "version.txt")
一个常见的用例是根据某种版本控制机制(例如当前 Git 标签)动态定义 version
。这可以通过以下方式完成:
from conan import ConanFile
from conan.tools.scm import Git
class Pkg(ConanFile):
name = "pkg"
def set_version(self):
git = Git(self, self.recipe_folder)
self.version = git.run("describe --tags")
set_version()
方法可以决定定义 version
值,而不受潜在的 --version=xxx
命令行参数的影响,该参数甚至可以完全被 set_version()
忽略。开发者有责任提供一个正确的 set_version()
实现。
def set_version(self):
# This will always assign "2.1" as version, ignoring ``--version`` command line argument
# and without erroring or warning
self.version = "2.1"
如果提供了命令行参数 --version=xxx
,它将被初始化到 self.version
属性中,因此 set_version()
方法可以读取和使用它。
def set_version(self):
# Takes the provided command line ``--version`` argument and creates a version appending to
# it the ".extra" string
self.version = self.version + ".extra"
警告
set_version()
方法是 version
属性的替代方案。不建议或不支持同时定义 version
类属性和 set_version()
方法。