conan create¶

$ conan create -h
usage: conan create [-h] [-v [V]] [-cc CORE_CONF] [-f FORMAT]
                    [--out-file OUT_FILE] [--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)

options:
  -h, --help            show this help message and exit
  -v [V]                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
  -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.
  --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
  -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
  -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)
  -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.
  -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
  --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

命令 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，并且它只会在二进制文件从源代码构建时启动测试包。

将 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 相同（参见图信息 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 中的方法

将配方导出到缓存
1. init()
2. set_name()
3. set_version()
4. export()
5. export_sources()
计算依赖图
1. ìnit()
2. config_options()
3. configure()
4. requirements()
5. build_requirements()
计算必要的包
1. validate_build()
2. validate()
3. package_id()
4. layout()
5. system_requirements()
安装包
1. source()
2. build_id()
3. generate()
4. build()
5. package()
6. package_info()

如果包不是从源代码构建的，则不会调用 安装包 步骤中的 generate()、build() 和 package() 步骤。

之后，如果您的项目中有名为 test_package 的文件夹，或者您使用 --test-folder 标志调用 conan create 命令，则该命令将按以下顺序调用该文件夹内 conanfile.py 文件的各种方法：

启动测试包
1. (测试包) init()
2. (测试包) set_name()
3. (测试包) set_version()
计算依赖图
1. (测试包) config_options()
2. (测试包) configure()
3. (测试包) requirements()
4. (测试包) build_requirements()
5. ìnit()
6. config_options()
7. configure()
8. requirements()
9. build_requirements()
计算必要的包
1. validate_build()
2. validate()
3. package_id()
4. layout()
5. (测试包) validate_build()
6. (测试包) validate()
7. (测试包) package_id()
8. (测试包) layout()
9. system_requirements()
10. (测试包) system_requirements()
安装包
1. build_id()
2. generate()
3. build()
4. package_info()
测试包
1. (测试包) build()
2. (测试包) test()

带有 (test package) 的函数属于 test_package 文件夹中的 conanfile.py。如果项目已经安装，则会跳过 安装包 步骤中的 build_id()、generate() 和 build() 步骤。通常，它应该与之前“安装包”步骤中的安装方式相同。

构建模式¶

命令 conan create --build=<xxxx> 的构建模式与构建模式中记载的 conan install 模式非常相似，但存在一些差异。

默认情况下，conan create 定义了 --build=current_pkg/current_version 以强制从源代码构建当前修订版。这假定源代码（配方、C/C++ 代码）已更改，并将创建新的修订版。如果不是这种情况，则建议使用 --build=missing:current_pkg/current_version 以避免从源代码重新构建已存在的二进制文件。

当命令行中定义了 --build=xxx 参数时，自动定义的 --build=current_pkg/current_version 将不再传递，并且也应将其作为显式参数传递。

注意

最佳实践

在大多数情况下，不鼓励为给定的 recipe_revision 和 package_id 拥有多个 package_revision，因为它意味着不必要地从源代码重新构建已经存在的二进制文件。因此，不鼓励在没有任何源代码更改会导致新 recipe_revision 的情况下重复使用 conan create，建议的方法是使用 conan create . --build=missing:[pattern]。

另请参阅

在专用教程中阅读更多关于创建包的信息
阅读更多关于测试 Conan 包的信息