Consumer commands - conan install - 《conan 中文文档 v1.27》

build options
env variables
settings
options
reference

本文档翻译自：https://docs.conan.io/en/latest/reference/commands/consumer/install.html

$ conan install [-h] [-g GENERATOR] [-if INSTALL_FOLDER] [-m [MANIFESTS]]
                [-mi [MANIFESTS_INTERACTIVE]] [-v [VERIFY]]
                [--no-imports] [-j JSON] [-b [BUILD]] [-r REMOTE] [-u]
                [-l [LOCKFILE]] [-e ENV_HOST] [-e:b ENV_BUILD]
                [-e:h ENV_HOST] [-o OPTIONS_HOST] [-o:b OPTIONS_BUILD]
                [-o:h OPTIONS_HOST] [-pr PROFILE_HOST]
                [-pr:b PROFILE_BUILD] [-pr:h PROFILE_HOST]
                [-s SETTINGS_HOST] [-s:b SETTINGS_BUILD]
                [-s:h SETTINGS_HOST]
                path_or_reference [reference]

安装配方中指定的要求(conanfile.py或conanfile.txt)。
它还可以用于安装指定引用的具体软件包。
如果在本地缓存中未找到任何要求，它将从远程服务器检索配方，并在已配置的远程中顺序查找。
下载配方后，它将尝试仅从检索配方的远程下载匹配指定设置的二进制软件包。如果找不到二进制包，则可以使用 “–build” 选项从源代码中构建。
安装软件包后，Conan将为指定的生成器写入文件。

positional arguments:
  path_or_reference     包含配方的文件夹的路径（conanfile.py或conanfile.txt）或配方文件。例如 ./my_project/conanfile.txt。 也可能是reference
  reference             第一个的conanfile路径参考参数：user/channel，version@user/channel 或 pkg/version@user/channel（如果声明了名称或版本在conanfile.py中，它们应该匹配）
optional arguments:
  -h, --help            show this help message and exit
  -g GENERATOR, --generator GENERATOR
                        Generators to use
  -if INSTALL_FOLDER, --install-folder INSTALL_FOLDER
                        使用此目录作为放置的目录 generatorfiles。例如,conaninfo / conanbuildinfo.txt
  -m [MANIFESTS], --manifests [MANIFESTS]
                        在文件夹中安装依赖项清单以便稍后验证。默认文件夹为.conan_manifest，但可以更改。
  -mi [MANIFESTS_INTERACTIVE], --manifests-interactive [MANIFESTS_INTERACTIVE]
                        在文件夹中安装依赖项清单以便稍后验证，请求用户确认。默认文件夹为.conan_manifest，但可以更改
  -v [VERIFY], --verify [VERIFY]
                        根据存储的依赖项清单验证依赖项清单
  --no-imports          安装指定的包，但避免运行 imports
  -j JSON, --json JSON  路径到一个json文件，安装信息将在其中写入
  -b [BUILD], --build [BUILD]
                        可选，指定要从源代码构建哪些包。可以在一个命令上组合多个“——build”选项。对于依赖项, conanfile.py 的 'build_policy' 属性的优先于命令行。
                        可选参数: 
                        --build 强制构建所有包，不要使用二进制包。 
                        --build=never 不允许构建所有的包，使用二进制包或失败，如果没有找到二进制包。不能与其他“——build”选项组合。
                        --build=missing 如果没有找到二进制包，则从源构建包
                        --build=outdated 如果二进制包不是从最新的配方生成的，或者没有找到，则从源构建包。
                        --build=cascade 从源构建具有至少一个依赖项的包。
                        --build=[pattern] Build packages
                        from source whose package reference matches the
                        pattern. The pattern uses 'fnmatch' style wildcards.
                        Default behavior: If you omit the '--build' option,
                        the 'build_policy' attribute in conanfile.py will be
                        used if it exists, otherwise the behavior is like '--
                        build=never'.
  -r REMOTE, --remote REMOTE
                        查找指定的远程服务器
  -u, --update          检查上游远程是否有更新
  -l [LOCKFILE], --lockfile [LOCKFILE]
                                              包含'conan.lock'文件的文件夹或 lockfile的路径。如果包更改，Lockfile可以更新
  -e ENV_HOST, --env ENV_HOST
                        将在包构建期间设置的环境变量(主机)。例如: -e CXX=/usr/bin/clang++
  -e:b ENV_BUILD, --env:build ENV_BUILD
                        将在包生成期间设置的环境变量(构建机器)。例如: -e:b CXX=/usr/bin/clang++
  -e:h ENV_HOST, --env:host ENV_HOST
                        将在包构建期间设置的环境变量(主机)。例如: -e:h CXX=/usr/bin/clang++
  -o OPTIONS_HOST, --options OPTIONS_HOST
                        定义选项值(主机), 例如: -o Pkg:with_qt=true
  -o:b OPTIONS_BUILD, --options:build OPTIONS_BUILD
                        定义选项值(构建机器)，例如: -o:b Pkg:with_qt=true
  -o:h OPTIONS_HOST, --options:host OPTIONS_HOST
                        定义选项值(主机), 例如: -o:h Pkg:with_qt=true
  -pr PROFILE_HOST, --profile PROFILE_HOST
                        将指定的配置文件应用到主机上
  -pr:b PROFILE_BUILD, --profile:build PROFILE_BUILD
                        将指定的概要文件应用到构建机器
  -pr:h PROFILE_HOST, --profile:host PROFILE_HOST
                        将指定的配置文件应用到主机上
  -s SETTINGS_HOST, --settings SETTINGS_HOST
                        设置来构建包，覆盖默认值(主机)。例如: -s compiler=gcc
  -s:b SETTINGS_BUILD, --settings:build SETTINGS_BUILD
                        设置来构建包，覆盖默认值(构建机器)。例如: -s:b compiler=gcc
  -s:h SETTINGS_HOST, --settings:host SETTINGS_HOST
                        设置来构建包，覆盖默认值(主机)。例如: -s:h compiler=gcc

conan install 按以下顺序执行conanfile.py的方法：

config_options()
configure()
requirements()
package_id()
package_info()
deploy()

请注意，这描述了安装预构建二进制程序包的过程。如果必须构建软件包，请使用 conan install --build 执行以下操作：

config_options()
configure()
requirements()
package_id()
build_requirements()
build_id()
system_requirements()
source()
imports()
build()
package()
package_info()
deploy()

Examples

从 conanfile.txt 安装软件包要求，并使用一个选项和设置将其保存在当前目录中（其他设置将默认为 <userhome>/.conan/profiles/default 中的定义）：
```
$ conan install . -o pkg_name:use_debug_mode=on -s compiler=clang
```
在当前目录的conanfile.py文件中安装定义的要求，并在默认配置文件<userhome>/.conan/profiles/default中使用默认设置，并指定版本，用户和渠道（因为它们可能在配方中使用））：
```
class Pkg(ConanFile):
 name = "mypkg"
 # see, no version defined!
 def requirements(self):
     # 这个技巧允许依赖于相同用户/通道上的包
     self.requires("dep/0.3@%s/%s" % (self.user, self.channel))
 def build(self):
     if self.version == "myversion":
         # something specific for this version of the package.
```
```
$ conan install . myversion@someuser/somechannel
```
这些值被缓存在文件中，因此以后对本地命令（如conan build）的调用可以找到并使用此version，user和channel数据。
使用<userhome>/.conan/profiles/default中的默认选项和默认设置安装opencv/4.1.1@conan/stable参考：
```
$ conan install opencv/4.1.1@conan/stable
```
如果有新的上游版本可用，请安装opencv/4.1.1@conan/stable参考以更新配方和二进制软件包：
```
$ conan install opencv/4.1.1@conan/stable --update
```
build options
conan install 命令和 create 命令都接受--build选项，以指定从源代码构建哪些软件包。允许在一个命令行上组合多个--build选项，如果至少一个给定的构建选项选择了一个软件包，则可以从源代码构建软件包。对于依赖项，其conanfile.py中的可选build_policy属性可以覆盖给定命令行参数的行为。可能的值为：
--build：始终从源代码构建所有内容，包括依赖包。
--build=never：当请求的配置不匹配时，Conan将不会尝试构建软件包，在这种情况下，它将引发错误。此选项不能与其他--build选项结合使用。
--build=missing：Conan将尝试从任何活动的远程控制器或缓存上的请求配置，如果找不到二进制包就从源代码中构建软件包。
--build=outdated：如果没有使用当前配方构建二进制软件包，或者缺少二进制软件包，Conan将尝试从源代码构建软件包。
--build=cascade：Conan选择用于构建的程序包，其中至少一个依赖项被选择用于构建。这对于重建直接或间接依赖于已更改软件包的软件包很有用。
--build=[pattern]：软件包引用或仅软件包名称的fnmatch区分大小写模式。 Conan将强制构建其引用与给定模式匹配的软件包。可以指定几种模式，链接多个选项：
例如--build=pattern1 --build=pattern2可用于指定多个模式。
例如--build=zlib将匹配任何名为zlib的软件包（与zlib/*相同）。
例如--build=z*@conan/stable将匹配任何以z开头且以conan/stable作为user/channel的软件包。

如果省略**--build**选项，将在conanfile.py中查找build_policy属性。如果将其设置为missng或always，则将使用此构建选项，否则该命令的行为将与--build=never相同。

env variables

使用-e参数，您可以定义：
全局环境变量（-e SOME_VAR="SOME_VALUE"）。这些变量将在所有软件包中的构建步骤之前定义，并在构建执行后清除。
特定的程序包环境变量（-e zlib:SOME_VAR ="SOME_VALUE"）。这些变量将仅在指定的程序包（例如zlib）中定义。
您不仅可以为您的直接需求指定此变量，还可以为依赖关系图中的任何程序包指定此变量。
如果要定义环境变量，但要追加需求中声明的变量，则可以使用[]语法：

$ conan install . -e PATH=[/other/path]

这样，PATH变量中的第一个条目将是/other/path，但是在项目要求中声明的PATH值将使用系统路径分隔符附加在末尾。

settings

使用-s参数，您可以定义：
全局设置（-s compiler="Visual Studio"）。将适用于所有需求。
特定的软件包设置（-s zlib:compiler="MinGW"）。这些设置将仅应用于指定的软件包。它们也接受模式，例如-s *@myuser/*compiler=MinGW，这意味着具有用户名“myuser”的软件包将使用MinGW作为编译器。
您不仅可以针对您的直接 requires，还可以为依赖关系图中的任何程序包指定自定义设置。

options

使用-o参数，您只能定义特定的软件包选项。

$ conan install . -o zlib:shared=True
$ conan install . -o zlib:shared=True -o bzip2:option=132
# you can also apply the same options to many packages with wildcards:
$ conan install . -o *:shared=True

:::info Note
您可以使用概要文件来创建预定义的设置，选项和环境变量集。 :::

reference

可选的位置参数，如果使用的话，第一个参数应该是路径。如果引用指定了名称和/或版本，并且还在conanfile.py中声明了它们，则它们应该匹配，否则将引发错误。

$ conan install . # OK, user and channel will be None
$ conan install . user/testing # OK
$ conan install . version@user/testing # OK
$ conan install . pkg/version@user/testing # OK
$ conan install pkg/version@user/testing user/channel # Error, first arg is not a path

:::info Note
使用conan.conf 中的general.parallel_download实验配置，可以加快二进制文件的安装速度，以设置并行下载。 :::

conan install

build options

env variables

settings

options

reference