conan install¶
$ conan install -h
Migration: Successfully updated settings.yml
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.
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
此 conan install 命令是主要的 Conan 命令之一，用于解析和安装依赖项。
此命令执行以下操作
计算整个依赖关系图，根据由 settings、options、profiles 和 configuration 定义的当前配置。它解析版本范围、传递性依赖项、条件要求等，以构建依赖关系图。
评估图中每个包的二进制文件的存在性，无论是否有预编译的二进制文件可供下载，或者是否应从源代码构建（如
--build参数所指示）。如果二进制文件缺失，它不会重新计算依赖关系图以尝试回退到包含该配置二进制文件的先前版本。如果需要某个特定的依赖版本，则应明确指定。按依赖关系图的正确顺序，在本地缓存中下载预编译的二进制文件，或从源代码构建二进制文件。
根据“generators”的要求创建必要的文件，以便构建系统和其他工具可以定位本地安装的依赖项
（可选）执行所需的
deployers。
另请参阅
查看此命令的 JSON 格式输出。
Conanfile path or –requires¶
conan install 命令可以使用 2 个不同的信息来源。第一个是使用本地 conanfile.py 或 conanfile.txt，其中包含要使用的依赖项和 generators 的定义。
$ 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，而不是在命令行中定义内容。
Profiles, Settings, Options, Conf¶
有几个参数用于定义将使用的有效 profiles，包括“build”和“host”上下文。
默认情况下，参数指代“host”上下文，因此 --settings:host, -s:h 完全等同于 --settings, -s。此外，默认情况下，conan install 命令会使用 default profile 作为“build”和“host”上下文。这意味着如果尚未创建名为“default”的 profile，则会出错。
可以传递多个 profiles 定义作为参数，它们将从左到右组合（右边的优先级最高）
# The values of myprofile3 will have higher priority
$ conan install . -pr=myprofile1 -pr=myprofile2 -pr=myprofile3
注意
在各种位置搜索 Profiles，有关更多信息请参阅此处
如果在命令行中提供了 settings、options 和 conf 中的任何值，它们将创建一个 profile，该 profile 会与提供的其他 -pr（或未指定时的“default”）profiles 组合，无论参数顺序如何，其优先级都更高。
# 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
Generators and deployers¶
-g 参数允许在命令行中定义要使用的不同内置 generators
$ conan install --requires=zlib/1.2.13 -g CMakeDeps -g CMakeToolchain
请注意，通常情况下，建议将 generators 定义在 conanfile 中，只有在使用 --requires 的情况下，将其作为命令行参数会更必要。
Generators 旨在创建文件供构建系统定位依赖项，而 deployers 的主要用例是将文件从 Conan 缓存复制到用户空间，并对依赖关系图执行任何其他自定义操作，例如收集许可证、生成报告、将二进制文件部署到系统等。deployers 的语法为
# does a full copy of the dependencies binaries to the current user folder
$ conan install . --deployer=full_deploy
有 3 个内置的 deployers
full_deploy会将依赖项的二进制文件完整复制到本地文件夹中，并采用最小化的文件夹结构以避免不同包的文件和 artifact 之间发生冲突direct_deploy只复制直接依赖项，但不包含传递性依赖项。runtime_deploy将所有共享库和依赖项的可执行文件（如.so、.dll或.dylib文件）部署到一个扁平的目录结构中。默认情况下会复制库的符号链接，可以通过布尔配置tools.deployer:symlinks进行管理。(自 Conan 2.5.0 起可用)
一些 generators 可能具有重新定义目标“package folder”的能力。这意味着如果使用像 CMakeDeps 这样的其他 generator 来指向包，它将指向本地部署的副本，而不是 Conan 缓存中的原始包。有关完整示例，请参见为开发者使用创建与 Conan 无关的依赖项部署。
也可以编写自定义用户 deployers，这是一个强大的扩展点。有关自定义 deployers 的更多信息，请参阅Deployers。
也可以使用 --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/*"
--deployer-package 参数是一个模式，接受多个值，所有匹配任何已定义模式的包引用都会执行其 deploy() 方法。这包括否定模式，例如 --deployer-package=~pkg/* 将对除 pkg 配方之外的所有包执行 deploy() 方法。--deployer-folder 参数也将影响此部署的输出位置。请参阅deploy() 方法。
如果多个已部署的包部署到同一位置，它们有责任确保在使用相同文件名时不会相互覆盖其二进制文件。例如，如果多个包 deploy() 一个名为“License.txt”的文件，则每个配方都有责任创建一个包含包名称和/或版本的中间文件夹以使其独一无二，从而使其他配方的 deploy() 方法不会覆盖之前部署的“License.txt”文件。
Name, version, user, channel¶
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
Lockfiles¶
conan install 命令有几个参数用于加载和生成 lockfiles。默认情况下，如果在配方旁边或当前工作目录（如果未提供路径）中找到 conan.lock 文件，它将用作输入 lockfile。
Lockfiles 默认是严格的，这意味着如果存在某个 requires 并且在 lockfile 中找不到匹配的锁定引用，则会出错并停止。对于 lockfile 预期不完整的情况（因为可能存在新的依赖项），可以使用 --lockfile-partial 参数。
默认情况下，conan install 不会生成输出 lockfile，但如果提供了指向文件名的 --lockfile-out 参数，例如 --lockfile-out=result.lock，则将从当前依赖关系图生成一个 lockfile。如果提供了 --lockfile-clean 参数，则结果 lockfile 中将删除当前依赖关系图中未使用的所有版本和修订。
假设我们已经有一个 conan.lock 输入 lockfile，但我们刚刚向一个新依赖项添加了新的 requires = "newpkg/1.0"。我们可以解析依赖项，锁定所有以前锁定的版本，同时允许解析 lockfile 中以前不存在的新依赖项，并将其存储在新位置，或覆盖现有 lockfile
# --lockfile=conan.lock is the default, not necessary
$ conan install . --lockfile=conan.lock --lockfile-partial --lockfile-out=conan.lock
此外，大多数 lockfile 操作更适合通过 conan lock 命令来管理。
Update¶
conan install 命令有一个 --update 参数，它将强制重新评估依赖关系图中的选定项，允许将依赖项更新到最新版本（如果使用版本范围），或更新到同一版本的最新修订（当这些版本未锁定在给定 lockfile 中时）。传递 --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 参数将查找命令中指定的所有远程仓库，以查找可能的较新版本，并且不会在找到第一个较新版本时停止。
Build modes¶
conan install --build=<mode> 参数控制从源代码构建包的行为。默认行为是如果不存在二进制文件则失败，并显示“missing binary”错误消息，但定义了 build_policy = "missing" 策略的包除外，但这可以通过 --build 参数更改。
可能的值有
--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=never 策略可用于强制永不从源代码构建，即使是定义了 build_policy = "missing" 策略的包配方也是如此。
--build=compatible:[pattern] 是一个 实验性 新模式，允许使用与当前配置不同的配置构建缺失的二进制文件。例如，如果当前 profile 的 compiler.cppstd=14，但某个包由于需要至少 compiler.cppstd=17 而引发“invalid”配置错误，并且二进制兼容性（例如在 compatibility.py 插件中定义）允许将其作为兼容二进制文件，那么 Conan 将从源代码构建该依赖包，并应用 compiler.cppstd=17。
--build=[pattern] 使用一个模式，因此应使用类似 --build="zlib/*" 的模式来匹配 zlib 包的任何版本，而仅使用 --build=zlib 将不起作用。
注意
最佳实践
使用 --build="*" 或任何其他 --build="pkg/*" 或类似模式强制重新构建现有二进制文件不是推荐的做法。如果二进制文件已经存在，没有理由从源代码重新构建。CI 管道应特别注意不要这样做，通常更推荐使用 --build=missing 和 --build=missing:[pattern]。
--build=cascade 模式部分是遗留的，在大多数情况下不应使用。package_id 计算才是决定需要构建什么的主导因素。此模式在 Conan 2 中仅保留用于特殊情况，例如从损坏的系统中恢复，但不建议用于正常的生产环境。