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.

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 命令之一,用于解析和安装依赖项。

此命令执行以下操作:

  • 根据设置、选项、配置文件和配置定义的当前配置,计算整个依赖关系图。它解析版本范围、传递依赖项、条件需求等,以构建依赖关系图。

  • 评估图中每个包的二进制文件的存在性,无论是是否有预编译的二进制文件可供下载,还是应该从源代码构建(如 --build 参数所指示)。如果二进制文件缺失,它不会重新计算依赖关系图以尝试回退到包含该配置的二进制文件的先前版本。如果需要特定依赖版本,应明确要求。

  • 根据依赖关系图的正确顺序,下载预编译的二进制文件或从源代码在本地缓存中构建二进制文件。

  • 根据“生成器”的请求创建必要的文件,以便构建系统和其他工具可以找到本地安装的依赖项。

  • 可选地,执行所需的 deployers

另请参阅

Conanfile 路径或 –requires

conan install 命令可以使用 2 种不同的信息来源。第一种是使用本地的 conanfile.pyconanfile.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 而不是在命令行中定义内容。

配置文件、设置、选项、配置

有几个参数用于定义将使用的有效配置文件,包括“构建”和“主机”上下文。

默认情况下,参数指的是“主机”上下文,所以 --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

注意

配置文件在各种位置进行搜索,更多信息请参见此处

如果命令行中提供了任何 settingsoptionsconf 的值,它们将创建一个与提供的其他 -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

请注意,在一般情况下,推荐的方法是将 generators 定义在 conanfile 中,只有在使用 --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 文件)到一个扁平的目录结构中。库的符号链接默认会被复制,并且可以通过布尔配置 tools.deployer:symlinks 进行管理。(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/*"
# 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/* 将执行所有包的 deploy() 方法,除了 pkg 配方。 --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 参数将检查命令中指定的所有远程仓库,以查找可能的新版本,并且不会在找到第一个新版本时停止。

构建模式

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] 是一个实验性新模式,它允许使用与当前配置不同的配置构建缺失的二进制文件。例如,如果当前配置文件有 compiler.cppstd=14,但某个包引发“无效”配置错误,因为它至少需要 compiler.cppstd=17,并且二进制兼容性(例如在 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 中仅用于特殊情况,例如从损坏的系统中恢复,但不推荐用于正常的生产用途。