conan create¶
$ conan create -h
usage: conan create [-h] [-f FORMAT] [--out-file OUT_FILE]
[-v [{quiet,error,warning,notice,status,verbose,debug,v,trace,vv}]]
[-cc CORE_CONF] [--name NAME] [--version VERSION]
[--user USER] [--channel CHANNEL] [-l LOCKFILE]
[--lockfile-partial] [--lockfile-out LOCKFILE_OUT]
[--lockfile-clean]
[--lockfile-overrides LOCKFILE_OVERRIDES] [-b BUILD]
[-r REMOTE | -nr] [-u [UPDATE]] [-pr PROFILE]
[-pr:b PROFILE_BUILD] [-pr:h PROFILE_HOST]
[-pr:a PROFILE_ALL] [-o OPTIONS] [-o:b OPTIONS_BUILD]
[-o:h OPTIONS_HOST] [-o:a OPTIONS_ALL] [-s SETTINGS]
[-s:b SETTINGS_BUILD] [-s:h SETTINGS_HOST]
[-s:a SETTINGS_ALL] [-c CONF] [-c:b CONF_BUILD]
[-c:h CONF_HOST] [-c:a CONF_ALL] [--build-require]
[-tf TEST_FOLDER] [-tm] [-bt BUILD_TEST]
[path]
Create a package.
positional arguments:
path Path to a folder containing a recipe (conanfile.py).
Defaults to current directory
options:
-h, --help show this help message and exit
-f FORMAT, --format FORMAT
Select the output format: json
--out-file OUT_FILE Write the output of the command to the specified file
instead of stdout.
-v [{quiet,error,warning,notice,status,verbose,debug,v,trace,vv}]
Level of detail of the output. Valid options from less
verbose to more verbose: -vquiet, -verror, -vwarning,
-vnotice, -vstatus, -v or -vverbose, -vv or -vdebug,
-vvv or -vtrace
-cc CORE_CONF, --core-conf CORE_CONF
Define core configuration, overwriting global.conf
values. E.g.: -cc core:non_interactive=True
-b BUILD, --build BUILD
Optional, specify which packages to build from source.
Combining multiple '--build' options on one command
line is allowed. Possible values: --build=never
Disallow build for all packages, use binary packages
or fail if a binary package is not found, it cannot be
combined with other '--build' options. --build=missing
Build packages from source whose binary package is not
found. --build=cascade Build packages from source that
have at least one dependency being built from source.
--build=[pattern] Build packages from source whose
package reference matches the pattern. The pattern
uses 'fnmatch' style wildcards, so '--build="*"' will
build everything from source. --build=~[pattern]
Excluded packages, which will not be built from the
source, whose package reference matches the pattern.
The pattern uses 'fnmatch' style wildcards.
--build=missing:[pattern] Build from source if a
compatible binary does not exist, only for packages
matching pattern. --build=compatible:[pattern]
(Experimental) Build from source if a compatible
binary does not exist, and the requested package is
invalid, the closest package binary following the
defined compatibility policies (method and
compatibility.py)
--build-require Whether the package being created is a build-require
(to be used as tool_requires() by other packages)
-tf TEST_FOLDER, --test-folder TEST_FOLDER
Alternative test folder name. By default it is
"test_package". Use "" to skip the test stage
-tm, --test-missing Run the test_package checks only if the package is
built from source but not if it already existed (using
--build=missing)
-bt BUILD_TEST, --build-test BUILD_TEST
Same as '--build' but only for the test_package
requires. By default if not specified it will take the
'--build' value if specified
reference arguments:
--name NAME Provide a package name if not specified in conanfile
--version VERSION Provide a package version if not specified in
conanfile
--user USER Provide a user if not specified in conanfile
--channel CHANNEL Provide a channel if not specified in conanfile
lockfile arguments:
-l LOCKFILE, --lockfile LOCKFILE
Path to a lockfile. Use --lockfile="" to avoid
automatic use of existing 'conan.lock' file
--lockfile-partial Do not raise an error if some dependency is not found
in lockfile
--lockfile-out LOCKFILE_OUT
Filename of the updated lockfile
--lockfile-clean Remove unused entries from the lockfile
--lockfile-overrides LOCKFILE_OVERRIDES
Overwrite lockfile overrides
remote arguments:
-r REMOTE, --remote REMOTE
Look in the specified remote or remotes server
-nr, --no-remote Do not use remote, resolve exclusively in the cache
-u [UPDATE], --update [UPDATE]
Will install newer versions and/or revisions in the
local cache for the given reference name, or all
references in the graph if no argument is supplied.
When using version ranges, it will install the latest
version that satisfies the range. It will update to
the latest revision for the resolved version range.
profile arguments:
-pr PROFILE, --profile PROFILE
Apply the specified profile. By default, or if
specifying -pr:h (--profile:host), it applies to the
host context. Use -pr:b (--profile:build) to specify
the build context, or -pr:a (--profile:all) to specify
both contexts at once
-pr:b PROFILE_BUILD, --profile:build PROFILE_BUILD
-pr:h PROFILE_HOST, --profile:host PROFILE_HOST
-pr:a PROFILE_ALL, --profile:all PROFILE_ALL
-o OPTIONS, --options OPTIONS
Apply the specified options. By default, or if
specifying -o:h (--options:host), it applies to the
host context. Use -o:b (--options:build) to specify
the build context, or -o:a (--options:all) to specify
both contexts at once. Example:
-o="pkg/*:with_qt=True"
-o:b OPTIONS_BUILD, --options:build OPTIONS_BUILD
-o:h OPTIONS_HOST, --options:host OPTIONS_HOST
-o:a OPTIONS_ALL, --options:all OPTIONS_ALL
-s SETTINGS, --settings SETTINGS
Apply the specified settings. By default, or if
specifying -s:h (--settings:host), it applies to the
host context. Use -s:b (--settings:build) to specify
the build context, or -s:a (--settings:all) to specify
both contexts at once. Example: -s="compiler=gcc"
-s:b SETTINGS_BUILD, --settings:build SETTINGS_BUILD
-s:h SETTINGS_HOST, --settings:host SETTINGS_HOST
-s:a SETTINGS_ALL, --settings:all SETTINGS_ALL
-c CONF, --conf CONF Apply the specified conf. By default, or if specifying
-c:h (--conf:host), it applies to the host context.
Use -c:b (--conf:build) to specify the build context,
or -c:a (--conf:all) to specify both contexts at once.
Example:
-c="tools.cmake.cmaketoolchain:generator=Xcode"
-c:b CONF_BUILD, --conf:build CONF_BUILD
-c:h CONF_HOST, --conf:host CONF_HOST
-c:a CONF_ALL, --conf:all CONF_ALL
命令 conan create 从 path 中指定的配方创建包。
此命令首先将配方 导出 到本地缓存，然后构建并创建包。如果找到 test_package 文件夹（您可以使用 -tf 参数或配方属性 test_package_folder 更改文件夹名称），则该命令将运行消费者项目，以确保已正确创建包。请查看 测试 Conan 包 部分，以了解有关如何测试您的 Conan 包的更多信息。
提示
有时您希望 跳过/禁用测试阶段。在这种情况下，您可以将空值作为 -tf 参数传递来跳过/禁用测试包阶段
$ conan create . --test-folder=""
您可能还需要执行 conan create . --build=missing，以便如果服务器上已存在二进制文件，则不构建包。如果您还想在二进制文件已经存在时避免 test_package 步骤，则可以使用 conan create . --build=missing --test-missing，它仅在从源代码构建二进制文件时才启动 test-package。
使用带有构建需求的 conan create¶
参数 --build-require 允许使用“构建”上下文的配置和设置来创建包，就像它是一个 build_require 一样。此功能允许以与稍后使用它们的方式一致的方式创建包。
$ conan create . --name=cmake --version=3.23.1 --build-require
Conan create 输出¶
命令 conan create ... --format=json 创建一个 json 输出，其中包含完整的依赖关系图信息。此 json 与使用 conan graph info 创建的 json 相同（请参阅 graph info json 格式），其中包含有关二进制文件的扩展信息，例如更完整的 cpp_info 字段。此生成的 json 是正在创建的包配方的依赖关系图，不包括所有 test_package 和 test_package/conanfile.py 的其他可能的依赖项。这些依赖项仅存在于 test_package 功能中，因此不属于“主要”产品或包。如果您有兴趣捕获包含 test_package 的依赖关系图（在大多数情况下可能不需要），则可以运行 conan test 命令单独进行。
使用 --lockfile-out 参数创建的 lockfile 也是如此。lockfile 将仅包含创建的包及其传递依赖项的版本，但不会包含 test_package 或 test_package/conanfile.py 的传递依赖项。可以使用 conan test 命令捕获包含这些内容的 lockfile（尽管同样，这可能不是真正必要的）
注意
最佳实践
通常，应避免在 test_package/conanfile.py 中使用除被测包以外的其他依赖项。 test_package 功能应作为简单的检查，以确保已正确创建包。将额外的依赖项添加到 test_package 可能会表明检查不直接或其功能被滥用。如果出于任何原因，您的 test_package 具有其他依赖项，则可以使用 --build-test 参数控制其构建。
方法执行顺序¶
命令 conan create 以以下顺序执行 方法 的 conanfile.py
- 将配方导出到缓存
init()set_name()set_version()export()export_sources()
- 计算依赖关系图
ìnit()config_options()configure()requirements()build_requirements()
- 计算必要的包
validate_build()validate()package_id()layout()system_requirements()
- 安装包
source()build_id()generate()build()package()package_info()
步骤 generate()、build()、package() 在“安装包”步骤中将不会被调用，如果包不是从源代码构建的。
之后，如果您在项目中有一个名为 test_package 的文件夹，或者使用 --test-folder 标志调用 conan create 命令，则该命令将以以下顺序调用文件夹中 conanfile.py 文件的方法
- 启动 test_package
(test package)
init()(test package)
set_name()(test package)
set_version()
- 计算依赖关系图
(test package)
config_options()(test package)
configure()(test package)
requirements()(test package)
build_requirements()ìnit()config_options()configure()requirements()build_requirements()
- 计算必要的包
validate_build()validate()package_id()layout()(test package)
validate_build()(test package)
validate()(test package)
package_id()(test package)
layout()system_requirements()(test package)
system_requirements()
- 安装包
build_id()generate()build()package_info()
- 测试包
(test package)
build()(test package)
test()
带有 (test package) 的函数属于 test_package 文件夹中的 conanfile.py。如果在“安装包”步骤中项目已经安装，则步骤 build_id()、generate()、build() 将被跳过。通常，它应该像在之前的“安装包”步骤中安装的那样安装。
在使用 cmake_layout() 功能在 test_package 内部时，可以使用 conf tools.cmake.cmake_layout:test_folder 来定义 test_package 的构建工件的位置。请参阅 cmake_layout() 文档。同样，构建工件的完整路径将由 self.folders.build_folder_vars 属性定义。
构建模式¶
命令 conan create --build=<xxxx> 的构建模式与 构建模式 中记录的 conan install 命令非常相似，但有一些区别。
默认情况下，conan create 将 --build=current_pkg/current_version 定义为强制从源代码构建当前修订版。这假定源代码（配方、C/C++ 代码）已更改，并且将创建一个新修订版。如果不是这种情况，则建议使用 --build=missing:current_pkg/current_version 或 --build="missing:&" 以避免从源代码重新构建已存在的二进制文件。
如果在命令行中定义了 --build=xxx 参数，则不再传递自动定义的 --build=current_pkg/current_version，并且也应将其作为显式参数传递。
注意
最佳实践
对于给定的 recipe_revision 和 package_id 拥有多个 package_revision 在大多数情况下是不鼓励的，因为它意味着不必要地从源代码重新构建已经存在的二进制文件。因此，不进行任何导致新 recipe_revision 的源代码更改的情况下，重复使用 conan create 命令是不鼓励的，并且使用 conan create . --build=missing:[pattern] 将是推荐的方法。
另请参阅
请阅读 专用教程，了解有关创建包的更多信息
请阅读 测试 Conan 包 的更多信息