conan install¶
$ conan install -h
usage: conan install [-h] [-v [V]] [-cc CORE_CONF] [-f FORMAT]
[--out-file OUT_FILE] [--name NAME] [--version VERSION]
[--user USER] [--channel CHANNEL] [--requires REQUIRES]
[--tool-requires TOOL_REQUIRES] [-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] [-l LOCKFILE]
[--lockfile-partial] [--lockfile-out LOCKFILE_OUT]
[--lockfile-clean]
[--lockfile-overrides LOCKFILE_OVERRIDES] [-g GENERATOR]
[-of OUTPUT_FOLDER] [-d DEPLOYER]
[--deployer-folder DEPLOYER_FOLDER]
[--deployer-package DEPLOYER_PACKAGE] [--build-require]
[--envs-generation {false}]
[path]
Install the requirements specified in a recipe (conanfile.py or conanfile.txt).
It can also be used to install packages without a conanfile, using the
--requires and --tool-requires arguments.
If any requirement is not found in the local cache, it will iterate the remotes
looking for it. When the full dependency graph is computed, and all dependencies
recipes have been found, it will look for binary packages matching the current settings.
If no binary package is found for some or several dependencies, it will error,
unless the '--build' argument is used to build it from source.
After installation of packages, the generators and deployers will be called.
positional arguments:
path Path to a folder containing a recipe (conanfile.py or
conanfile.txt) or to a recipe file. e.g.,
./my_project/conanfile.txt. Defaults to the current
directory when no --requires or --tool-requires is
given
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
--requires REQUIRES Directly provide requires instead of a conanfile
--tool-requires TOOL_REQUIRES
Directly provide tool-requires instead of a conanfile
-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
-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
-g GENERATOR, --generator GENERATOR
Generators to use
-of OUTPUT_FOLDER, --output-folder OUTPUT_FOLDER
The root output folder for generated and build files
-d DEPLOYER, --deployer DEPLOYER
Deploy using the provided deployer to the output
folder. Built-in deployers: 'full_deploy',
'direct_deploy', 'runtime_deploy'
--deployer-folder DEPLOYER_FOLDER
Deployer output folder, base build folder by default
if not set
--deployer-package DEPLOYER_PACKAGE
Execute the deploy() method of the packages matching
the provided patterns
--build-require Whether the provided path is a build-require
--envs-generation {false}
Generation strategy for virtual environment files for
the root
The conan install 命令是 Conan 的主要命令之一，用于解析和安装依赖项。
此命令执行以下操作：
计算当前由设置、选项、配置文件和配置定义的整个依赖关系图。它会解析版本范围、传递依赖项、条件需求等，以构建依赖关系图。
评估图中每个包的二进制文件的存在性，无论是否存在预编译的二进制文件可供下载，或者是否应从源代码构建（由
--build参数指示）。如果缺少二进制文件，它不会重新计算依赖关系图来尝试回退到包含该配置的二进制文件的先前版本。如果需要某个特定的依赖版本，应显式声明。按照依赖关系图的正确顺序，下载预编译的二进制文件，或从源代码构建二进制文件到本地缓存。
创建“生成器”请求的必要文件，以便构建系统和其他工具可以找到本地安装的依赖项。
可选地，执行所需的
deployers。
另请参阅
有关此命令的 JSON 格式输出，请参阅。
Conanfile 路径或 –requires¶
The conan install 命令可以使用 2 种不同的信息来源。第一种是使用本地 conanfile.py 或 conanfile.txt，其中包含要使用的依赖项和生成器的定义。
$ conan install . # there is a conanfile.txt or a conanfile.py in the cwd
$ conan install conanfile.py # also works, direct reference file
$ conan install myconan.txt # explicit custom name
$ conan install myfolder # there is a conanfile in "myfolder" folder
即使可以自定义名称，但在一般情况下，建议使用存储库根目录中默认的 conanfile.py 名称，这样用户就可以直接执行 git clone ... `` + ``conan install .。
另一种可能性是根本不使用 conanfile，而是直接在命令行中定义要安装的需求。
# Install the zlib/1.2.13 library
$ conan install --requires=zlib/1.2.13
# Install the zlib/1.2.13 and bzip2/1.0.8 libraries
$ conan install --requires=zlib/1.2.13 --requires=bzip2/1.0.8
# Install the cmake/3.23.5 and ninja/1.11.0 tools
$ conan install --tool-requires=cmake/3.23.5 --tool-requires=ninja/1.11.0
# Install the zlib/1.2.13 library and ninja/1.11.0 tool
$ conan install --requires=zlib/1.2.13 --tool-requires=ninja/1.11.0
在一般情况下，建议使用 conanfile 而不是在命令行中定义。
配置文件、设置、选项、Conf¶
有几个参数用于定义将使用的有效配置文件，包括“构建”和“主机”上下文。
默认情况下，参数引用“主机”上下文，因此 --settings:host, -s:h 等同于 --settings, -s。同样，默认情况下，conan install 命令将同时为“构建”和“主机”上下文使用 default 配置文件。这意味着，如果不存在名为“default”的配置文件，则会报错。
可以通过参数传递多个配置文件定义，它们将从左到右组合（右侧优先级最高）。
# The values of myprofile3 will have higher priority
$ conan install . -pr=myprofile1 -pr=myprofile2 -pr=myprofile3
注意
配置文件在各种位置进行搜索，此处可查看更多信息。
如果在命令行中提供了 settings、options 和 conf 的任何值，它们将创建一个与提供的其他 -pr（或未指定时的“default”）配置文件组合的配置文件，优先级更高，无论参数顺序如何。
# the final "host" profile will always be build_type=Debug, even if "myprofile"
# says "build_type=Release"
$ conan install . -pr=myprofile -s build_type=Debug
生成器和部署器¶
The -g argument allows to define in the command line the different built-in generators to be used.
$ conan install --requires=zlib/1.2.13 -g CMakeDeps -g CMakeToolchain
请注意，在一般情况下，推荐的方法是在 conanfile 中定义 generators，只有在使用 --requires 的情况下，才更有必要将其作为命令行参数。
生成器的目的是为构建系统创建文件以定位依赖项，而 deployers 的主要用例是从 Conan 缓存将文件复制到用户空间，并对依赖关系图执行任何其他自定义操作，例如收集许可证、生成报告、将二进制文件部署到系统等。部署器的语法是：
# does a full copy of the dependencies binaries to the current user folder
$ conan install . --deployer=full_deploy
有 3 个内置部署器：
full_deploy 将依赖项的二进制文件完整复制到本地文件夹，并具有最小的文件夹结构以避免不同包的文件和工件之间的冲突。
direct_deploy 仅复制直接依赖项，但不包括传递依赖项。
runtime_deploy 将所有共享库和依赖项的可执行文件部署到扁平的目录结构中，按原样保留子目录。
某些生成器可能能够重新定义目标“包文件夹”。这意味着，如果使用像 CMakeDeps 这样的其他生成器指向包，它将指向本地部署的副本，而不是 Conan 缓存中的原始包。请参阅 创建用于开发者使用的 Conan 不相关的依赖项部署 中的完整示例。
还可以编写自定义用户部署器，这是一个强大的扩展点。有关自定义部署器的更多信息，请参阅 部署器。
还可以使用 --deployer-package 调用包配方 deploy() 方法。
# Execute deploy() method of every recipe that defines it
$ conan install --requires=pkg/0.1 --deployer-package="*"
# Execute deploy() method only for "pkg" (any version) recipes
$ conan install --requires=pkg/0.1 --deployer-package="pkg/*"
# Execute deploy() method for all packages except the "zlib" (transitive dep) one
$ conan install --requires=pkg/0.1 --deployer-package="*" --deployer-package="~zlib/*"
The --deployer-package argument is a pattern and accepts multiple values, all package references matching any of the defined patterns will execute its deploy() method. This includes negated patterns, where for example --deployer-package=~pkg/* will execute the deploy() method for all packages except for that of the pkg recipe. The --deployer-folder argument will also affect the output location of this deployment. See the deploy() method.
如果多个已部署的包部署到同一位置，则它们有责任不相互覆盖具有相同文件名的二进制文件。例如，如果多个包 deploy() 一个名为“License.txt”的文件，则每个配方都有责任创建一个包含包名称和/或版本的中介文件夹，使其唯一，这样其他配方的 deploy() 方法就不会覆盖先前部署的“License.txt”文件。
名称、版本、用户、频道¶
The conan install command provides optional arguments for --name, --version, --user, --channel. These arguments might not be necessary in the majority of cases. Never for conanfile.txt and for conanfile.py only in the case that they are not defined in the recipe.
from conan import ConanFile
from conan.tools.scm import Version
class Pkg(ConanFile):
name = "mypkg"
def requirements(self):
if Version(self.version) >= "3.23":
self.requires("...")
# If we don't specify ``--version``, it will be None and it will fail
$ conan install . --version=3.24
锁定文件¶
The conan install command has several arguments to load and produce lockfiles. By default, if a conan.lock file is located beside the recipe or in the current working directory if no path is provided, will be used as an input lockfile.
Lockfiles are strict by default, that means that if there is some requires and it cannot find a matching locked reference in the lockfile, it will error and stop. For cases where it is expected that the lockfile will not be complete, as there might be new dependencies, the --lockfile-partial argument can be used.
By default, conan install will not generate an output lockfile, but if the --lockfile-out argument is provided, pointing to a filename, like --lockfile-out=result.lock, then a lockfile will be generated from the current dependency graph. If --lockfile-clean argument is provided, all versions and revisions not used in the current dependency graph will be dropped from the resulting lockfile.
Let’s say that we already have a conan.lock input lockfile, but we just added a new requires = "newpkg/1.0" to a new dependency. We could resolve the dependencies, locking all the previously locked versions, while allowing to resolve the new one, which was not previously present in the lockfile, and store it in a new location, or overwrite the existing lockfile.
# --lockfile=conan.lock is the default, not necessary
$ conan install . --lockfile=conan.lock --lockfile-partial --lockfile-out=conan.lock
Also, it is likely that the majority of lockfile operations are better managed by the conan lock command.
更新¶
The conan install command has an --update argument that will force the re-evaluation of the selected items of the dependency graph, allowing for the update of the dependencies to the latest version if using version ranges, or to the latest revision of the same version, when those versions are not locked in the given lockfile. Passing --update will check every package in the dependency graph, but it is also possible to pass a package name to the --update argument (it can be added to the command more than once with different names), to only update those packages, which avoids the re-evaluation of the whole graph.
$ conan install . --update # Update all packages in the graph
$ conan install . --update=openssl # Update only the openssl package
$ conan install . --update=openssl --update=boost # Update both openssl and boost packages
Note that the --update argument will look into all the remotes specified in the command for possible newer versions, and won’t stop at the first newer one found.
构建模式¶
The conan install --build=<mode> argument controls the behavior regarding building packages from source. The default behavior is failing if there are no existing binaries, with the “missing binary” error message, except for packages that define a build_policy = "missing" policy, but this can be changed with the --build argument.
Possible values are:
--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)
The --build=never policy can be used to force never building from source, even for package recipes that define the build_policy = "missing" policy.
The --build=compatible:[pattern] is an experimental new mode that allows building missing binaries with a configuration different than the current one. For example if the current profile has compiler.cppstd=14, but some package raises an “invalid” configuration error, because it needs at least compiler.cppstd=17, and the binary compatibiliy (defined for example in compatibility.py plugin) allows that as a compatible binary, then, Conan will build from source that dependency package applying compiler.cppstd=17.
The --build=[pattern] uses a pattern, so it should use something like --build="zlib/*" to match any version of the zlib package, as doing --build=zlib will not work.
注意
最佳实践
Forcing the rebuild of existing binaries with --build="*" or any other --build="pkg/*" or similar pattern is not a recommended practice. If a binary is already existing there is no reason to rebuild it from source. CI pipelines should be specially careful to not do this, and in general the --build=missing and --build=missing:[pattern] are more recommended.
The --build=cascade mode is partly legacy, and shouldn’t be used in most cases. The package_id computation should be the driver to decide what needs to be built. This mode has been left in Conan 2 only for exceptional cases, like recovering from broken systems, but it is not recommended for normal production usage.