conan install¶
$ conan install -h
usage: conan install [-h] [-v [V]] [-cc CORE_CONF] [-f FORMAT] [--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.
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
--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="*" Force
build from source for all packages. --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. --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.
-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
conan install 命令是 Conan 的主要命令之一，用于解析和安装依赖项。
此命令执行以下操作：
计算整个依赖关系图，用于由设置、选项、配置文件和配置定义的当前配置。它解析版本范围、传递依赖项、条件要求等，以构建依赖关系图。
评估图中每个包的二进制文件的存在性，无论是否存在要下载的预编译二进制文件，还是应从源代码构建（如
--build参数所指示）。如果缺少二进制文件，它将不会重新计算依赖关系图以尝试回退到包含该配置的二进制文件的先前版本。如果需要某个依赖项版本，则应明确要求。下载预编译的二进制文件，或按照依赖关系图的正确顺序从本地缓存中的源代码构建二进制文件。
创建 “生成器” 请求的必要文件，以便构建系统和其他工具可以找到本地安装的依赖项。
可选地，执行所需的
deployers。
另请参阅
查看此命令的 JSON 格式输出。
Conanfile 路径或 –requires¶
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¶
有几个参数用于定义将用于 “build” 和 “host” 上下文的有效配置文件。
默认情况下，参数指的是 “host” 上下文，因此 --settings:host, -s:h 与 --settings, -s 完全等效。此外，默认情况下，conan install 命令将对 “build” 和 “host” 上下文使用 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
生成器和部署器¶
-g 参数允许在命令行中定义要使用的不同内置生成器。
$ 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将依赖项的所有共享库和可执行文件（如.so、.dll或.dylib文件）部署到扁平的目录结构中。（自 Conan 2.5.0 起可用）
某些生成器可能具有重新定义目标 “包文件夹” 的能力。这意味着如果使用了其他指向包的生成器（如 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/*
--deployer-package 参数是一个模式，接受多个值，任何匹配定义模式的包引用都将执行其 deploy() 方法。--deployer-folder 参数也会影响此部署的输出位置。请参阅 deploy() 方法。
如果多个已部署的包部署到同一位置，则如果它们具有相同的文件名，则它们有责任不相互覆盖它们的二进制文件。例如，如果多个包 deploy() 一个名为 “License.txt” 的文件，则每个配方都有责任创建一个包含包名称和/或版本的中间文件夹，使其具有唯一性，以便其他配方的 deploy() 方法不会覆盖先前部署的 “License.txt” 文件。
名称、版本、用户、通道¶
conan install 命令为 --name, --version, --user, --channel 提供了可选参数。在大多数情况下，这些参数可能不是必需的。对于 conanfile.txt 永远不需要，对于 conanfile.py，仅在配方中未定义的情况下才需要。
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
锁定文件¶
conan install 命令有几个参数来加载和生成锁定文件。默认情况下，如果 conan.lock 文件位于配方旁边，或者如果未提供路径则位于当前工作目录中，则会将其用作输入锁定文件。
默认情况下，锁定文件是严格的，这意味着如果存在某些 requires 并且在锁定文件中找不到匹配的锁定引用，则会出错并停止。对于预期锁定文件不完整的情况，因为可能存在新的依赖项，可以使用 --lockfile-partial 参数。
默认情况下，conan install 不会生成输出锁定文件，但是如果提供了 --lockfile-out 参数，指向一个文件名，如 --lockfile-out=result.lock，则会从当前的依赖关系图中生成一个锁定文件。如果提供了 --lockfile-clean 参数，则当前依赖关系图中未使用的所有版本和修订都将从生成的锁定文件中删除。
假设我们已经有一个 conan.lock 输入锁文件，但我们刚刚在新的依赖项中添加了 requires = "newpkg/1.0"。我们可以解析依赖关系，锁定所有先前锁定的版本，同时允许解析新版本（该版本之前不存在于锁文件中），并将其存储在新位置或覆盖现有锁文件。
# --lockfile=conan.lock is the default, not necessary
$ conan install . --lockfile=conan.lock --lockfile-partial --lockfile-out=conan.lock
此外，大多数锁文件操作最好由 conan lock 命令管理。
更新¶
conan install 命令有一个 --update 参数，它将强制重新评估依赖关系图中所选的项目，如果使用版本范围，则允许将依赖项更新到最新版本，或者当这些版本未锁定在给定的锁文件中时，更新到相同版本的最新修订版本。传递 --update 将检查依赖关系图中的每个软件包，但也可以将软件包名称传递给 --update 参数（它可以多次添加到命令中，使用不同的名称），仅更新这些软件包，从而避免重新评估整个图。
$ 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
请注意，--update 参数将查看命令中指定的所有远程仓库，以查找可能存在的较新版本，并且不会在找到第一个较新版本时停止。