C++包管理工具:conan2常用命令详解
conan new
conan new
命令用于根据预定义或用户自定义的模板创建新的 Conan 配方(包含 conanfile.py
和其他相关文件)。
命令用法
$ conan new -h
用法:conan new [-h] [-v [V]] [-cc CORE_CONF] [--out-file OUT_FILE][-d DEFINE] [-f] [-o OUTPUT]模板名称
参数说明
参数 | 说明 |
---|---|
模板名称 | 模板名称,可以是预定义的内置模板或用户提供的模板。可用内置模板见下文。 |
-h, --help | 显示帮助信息 |
-v [V] | 输出详细级别(从低到高):-vquiet , -verror , -vwarning , -vnotice , -vstatus , -v /-vverbose , -vv /-vdebug , -vvv /-vtrace |
-cc CORE_CONF, --core-conf CORE_CONF | 定义核心配置,覆盖 global.conf 值(如:-cc core:non_interactive=True ) |
--out-file OUT_FILE | 将命令输出写入指定文件(而非标准输出) |
-d DEFINE, --define DEFINE | 定义模板参数(格式:key=value ,如:-d name=mypkg ) |
-f, --force | 如果文件已存在则强制覆盖 |
-o OUTPUT, --output OUTPUT | 指定生成文件的输出目录 |
功能说明
该命令会在当前工作目录创建新配方,并根据需要生成额外文件(如 CMakeLists.txt
或 test_package
文件夹)。这些文件可作为项目基础或用于调试。
每个模板都有必需和可选的用户定义变量,用于自定义生成的文件。
内置模板列表
模板名称 | 描述 | 必需变量 | 可选变量 |
---|---|---|---|
basic | 创建带示例代码和注释的基础配方(避免样板代码) | - | [name] , [version] , [description] , [requires1, requires2, …] , [tool_requires1, tool_requires2, …] |
alias | 创建指向目标配方的最小别名配方 | name | [version] , target |
cmake_lib | 创建 CMake 库目标(定义一个打印编译环境信息的函数) | name , version | [requires1, requires2, …] , [tool_requires1, tool_requires2, …] |
cmake_exe | 创建 CMake 可执行目标(定义一个打印编译环境信息的函数) | name , version | [requires1, requires2, …] , [tool_requires1, tool_requires2, …] |
header_lib | 创建头文件库(定义一个打印输出的函数) | name , version | [requires1, requires2, …] |
autotools_lib | 创建 Autotools 库 | name , version | - |
autotools_exe | 创建 Autotools 可执行文件 | name , version | - |
bazel_lib | 创建 Bazel 库(实验性功能) | name , version | - |
bazel_exe | 创建 Bazel 可执行文件(实验性功能) | name , version | - |
meson_lib | 创建 Meson 库 | name , version | - |
meson_exe | 创建 Meson 可执行文件 | name , version | - |
msbuild_lib | 创建 MSBuild 库 | name , version | - |
msbuild_exe | 创建 MSBuild 可执行文件 | name , version | - |
workspace | 创建包含三个可编辑项目的工作空间(liba , libb , app1 ) | - | [requires] |
注意:
- 所有
name
和version
变量默认值为mypkg
和0.1
- 预定义模板的输出在未来的版本中可能会发生变化
- Bazel 集成(BazelDeps, BazelToolchain)目前是实验性功能
使用示例
# 生成基础配方
$ conan new basic# 生成带依赖的配方
$ conan new basic -d name=mygame -d requires=math/1.0 -d requires=ai/1.3# 创建默认 CMake 库
$ conan new cmake_lib# 创建带依赖的 CMake 可执行文件
$ conan new cmake_exe -d name=game -d version=1.0 -d requires=math/3.14 -d requires=ai/1.0
自定义模板
创建自定义模板
- 在 Conan home 目录创建模板文件夹:
templates/command/new/模板名称
- 模板文件夹内使用 Jinja2 语法编写文件
- 通过
-d
参数传递模板变量
模板文件示例
文件路径:templates/command/new/mytemplate/conanfile.py
from conan import ConanFileclass Conan(ConanFile):name = "{{name}}"version = "{{version}}"license = "{{license}}"
使用自定义模板
$ conan new mytemplate -d name=pkg -d version=0.1 -d license=MIT
特殊说明
- 自动定义变量:
conan_version
(始终自动定义)package_name
(默认等于name
)
- 文件名也可参数化:
# 文件名:{{name}} {{contents}}
- 排除渲染文件:
- 创建
not_templates
文件列出不需要渲染的文件名(每行一个) - 支持通配符(如
*.png
)
- 创建
模板管理
- 使用
conan config install <url>
管理/共享模板 - 也可直接使用完整路径:
$ conan new /path/to/custom_template
关键提示
- 变量要求:
name
变量始终是必需的 - 列表转换:
requires
和tool_requires
变量会自动转换为列表 - 稳定警告:内置模板的输出在未来的 Conan 版本中可能会更改
conan create
conan create
命令用于根据指定的配方创建 Conan 包。
命令用法
$ conan create -h
用法:conan create [-h] [-v [V]] [-cc CORE_CONF] [-f FORMAT][--out-file OUT_FILE] [--name NAME] [--version VERSION][--user USER] [--channel CHANNEL] [-l LOCKFILE][--lockfile-partial] [--lockfile-out LOCKFILE_OUT][--lockfile-clean][--lockfile-overrides LOCKFILE_OVERRIDES] [-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] [--build-require][-tf TEST_FOLDER] [-tm] [-bt BUILD_TEST]path
参数说明
参数 | 说明 |
---|---|
path | 包含配方 (conanfile.py ) 的文件夹路径(必需) |
-h, --help | 显示帮助信息 |
-v [V] | 输出详细级别(从低到高):-vquiet , -verror , -vwarning , -vnotice , -vstatus , -v /-vverbose , -vv /-vdebug , -vvv /-vtrace |
-cc CORE_CONF, --core-conf CORE_CONF | 定义核心配置,覆盖 global.conf 值 |
-f FORMAT, --format FORMAT | 选择输出格式(目前仅支持 json ) |
--out-file OUT_FILE | 将命令输出写入指定文件(而非标准输出) |
--name NAME | 如果配方中未指定,提供包名称 |
--version VERSION | 如果配方中未指定,提供包版本 |
--user USER | 如果配方中未指定,提供用户 |
--channel CHANNEL | 如果配方中未指定,提供频道 |
-l LOCKFILE, --lockfile LOCKFILE | 指定锁文件路径。使用 --lockfile="" 禁用自动使用 conan.lock |
--lockfile-partial | 如果锁文件中缺少某些依赖项,不报错 |
--lockfile-out LOCKFILE_OUT | 指定更新后的锁文件名 |
--lockfile-clean | 从锁文件中移除未使用的条目 |
--lockfile-overrides LOCKFILE_OVERRIDES | 覆盖锁文件中的覆盖项 |
-b BUILD, --build BUILD | 构建模式控制(详见下方说明) |
-r REMOTE, --remote REMOTE | 在指定的远程服务器查找 |
-nr, --no-remote | 不使用远程服务器,仅在本地缓存解析 |
-u [UPDATE], --update [UPDATE] | 更新本地缓存中的版本/修订版(可指定名称或更新所有) |
-pr PROFILE, --profile PROFILE | 应用指定的配置文件(默认应用于主机上下文) |
-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 | 应用指定的选项(默认应用于主机上下文) |
-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 | 应用指定的设置(默认应用于主机上下文) |
-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 | 应用指定的配置项(默认应用于主机上下文) |
-c:b CONF_BUILD, --conf:build CONF_BUILD | 应用于构建上下文的配置项 |
-c:h CONF_HOST, --conf:host CONF_HOST | 应用于主机上下文的配置项 |
-c:a CONF_ALL, --conf:all CONF_ALL | 应用于所有上下文的配置项 |
--build-require | 指定正在创建的包是构建依赖(将用作其他包的 tool_requires() ) |
-tf TEST_FOLDER, --test-folder TEST_FOLDER | 指定测试文件夹名(默认为 test_package ,设为空字符串 "" 跳过测试) |
-tm, --test-missing | 仅当包从源码构建时运行测试(与 --build=missing 配合使用) |
-bt BUILD_TEST, --build-test BUILD_TEST | 为 test_package 的依赖项指定构建模式(默认继承 --build 的值) |
核心功能
此命令将配方导出到本地缓存,然后构建并创建包。如果存在 test_package
文件夹(可通过 -tf
参数或配方属性 test_package_folder
修改名称),命令将运行消费项目以验证包是否正确创建。
跳过测试
$ conan create . --test-folder="" # 完全跳过测试阶段
$ conan create . --build=missing --test-missing # 仅当从源码构建时运行测试
创建构建依赖包
$ conan create . --name=cmake --version=3.23.1 --build-require
构建模式 (-b/--build
)
模式 | 说明 |
---|---|
--build=never | 禁止构建,仅使用二进制包(找不到则失败) |
--build=missing | 构建找不到二进制包的源码 |
--build=cascade | 构建至少有一个依赖需从源码构建的包 |
--build=[pattern] | 构建包引用匹配模式的源码(支持 fnmatch 通配符) |
--build=~[pattern] | 排除匹配模式的包(不构建) |
--build=missing:[pattern] | 仅为匹配模式的包构建缺失的二进制 |
--build=compatible:[pattern] | (实验性) 为匹配模式的包构建兼容的二进制 |
注意:默认行为是
--build=current_pkg/current_version
(强制为当前修订版构建)。如果指定任何--build
参数,此默认行为将被覆盖。
JSON 输出与锁文件
$ conan create ... --format=json # 生成包含完整依赖图信息的 JSON
$ conan create ... --lockfile-out=conan.lock # 生成更新的锁文件
生成的 JSON/锁文件 仅包含主包及其依赖,不包括
test_package
的依赖。
方法执行顺序
主配方执行流程
- 导出配方到缓存
init()
set_name()
set_version()
export()
export_sources()
- 计算依赖图
init()
(再次)config_options()
configure()
requirements()
build_requirements()
- 计算必要包
validate_build()
validate()
package_id()
layout()
system_requirements()
- 安装包
source()
build_id()
generate()
build()
package()
package_info()
注意:如果不需要从源码构建,则跳过
generate()
,build()
,package()
步骤。
测试包执行流程(如果存在)
- 启动测试包
- (测试包)
init()
- (测试包)
set_name()
- (测试包)
set_version()
- (测试包)
- 计算依赖图
- (测试包)
config_options()
,configure()
,requirements()
,build_requirements()
- 主配方再次执行:
init()
,config_options()
,configure()
,requirements()
,build_requirements()
- (测试包)
- 计算必要包
- (测试包)
validate_build()
,validate()
,package_id()
,layout()
- (测试包)
system_requirements()
- (测试包)
- 安装包
build_id()
generate()
build()
- 测试包
- (测试包)
build()
- (测试包)
test()
- (测试包)
最佳实践
- 避免不必要的重建:
# 推荐方式(避免重建已存在的二进制) $ conan create . --build=missing:[pattern]
- 简化测试包:
test_package
应仅依赖被测试包,避免额外依赖- 如需控制测试包的依赖构建,使用
--build-test
- 谨慎处理修订版:
- 避免在配方/源码未更改时重复创建(会产生相同二进制的新包修订版)
conan install
conan install
是 Conan 的核心命令之一,用于解析并安装依赖项。
命令用法
$ conan install -h
用法: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]
参数说明
参数 | 说明 |
---|---|
path | 包含配方 (conanfile.py 或 conanfile.txt ) 的文件夹或文件路径(可选) |
-h, --help | 显示帮助信息 |
-v [V] | 输出详细级别(从低到高):-vquiet , -verror , -vwarning , -vnotice , -vstatus , -v /-vverbose , -vv /-vdebug , -vvv /-vtrace |
-cc CORE_CONF, --core-conf CORE_CONF | 定义核心配置,覆盖 global.conf 值 |
-f FORMAT, --format FORMAT | 选择输出格式(目前仅支持 json ) |
--out-file OUT_FILE | 将命令输出写入指定文件(而非标准输出) |
--name NAME | 如果配方中未指定,提供包名称 |
--version VERSION | 如果配方中未指定,提供包版本 |
--user USER | 如果配方中未指定,提供用户 |
--channel CHANNEL | 如果配方中未指定,提供频道 |
--requires REQUIRES | 直接提供依赖项(无需配方文件) |
--tool-requires TOOL_REQUIRES | 直接提供工具依赖项(无需配方文件) |
-b BUILD, --build BUILD | 构建模式控制(详见下方说明) |
-r REMOTE, --remote REMOTE | 在指定的远程服务器查找 |
-nr, --no-remote | 不使用远程服务器,仅在本地缓存解析 |
-u [UPDATE], --update [UPDATE] | 更新本地缓存中的版本/修订版(可指定名称或更新所有) |
-pr PROFILE, --profile PROFILE | 应用指定的配置文件(默认应用于主机上下文) |
-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 | 应用指定的选项(默认应用于主机上下文) |
-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 | 应用指定的设置(默认应用于主机上下文) |
-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 | 应用指定的配置项(默认应用于主机上下文) |
-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 | 指定锁文件路径。使用 --lockfile="" 禁用自动使用 conan.lock |
--lockfile-partial | 如果锁文件中缺少某些依赖项,不报错 |
--lockfile-out LOCKFILE_OUT | 指定更新后的锁文件名 |
--lockfile-clean | 从锁文件中移除未使用的条目 |
--lockfile-overrides LOCKFILE_OVERRIDES | 覆盖锁文件中的覆盖项 |
-g GENERATOR, --generator GENERATOR | 指定生成器(如 CMakeDeps , CMakeToolchain ) |
-of OUTPUT_FOLDER, --output-folder OUTPUT_FOLDER | 指定生成文件和构建文件的根输出目录 |
-d DEPLOYER, --deployer DEPLOYER | 使用部署器(内置选项:full_deploy , direct_deploy , runtime_deploy ) |
--deployer-folder DEPLOYER_FOLDER | 指定部署器输出目录(默认为构建文件夹) |
--deployer-package DEPLOYER_PACKAGE | 执行匹配包的 deploy() 方法(支持通配符) |
--build-require | 指定提供的路径是构建依赖 |
--envs-generation {false} | 根目录虚拟环境文件的生成策略 |
核心功能
此命令执行以下操作:
- 计算依赖图:根据设置、选项、配置文件和配置解析版本范围、传递依赖等。
- 评估二进制包:检查是否有预编译二进制可供下载,或是否需要从源码构建(由
--build
参数控制)。 - 下载或构建:按依赖顺序下载二进制包或在本地缓存中从源码构建。
- 生成文件:根据指定的生成器(
-g
)创建文件,供构建系统定位依赖项。 - 执行部署:可选地执行部署器(
-d
)进行文件复制或其他操作。
注意:如果找不到二进制包且未指定构建模式,命令将报错。
依赖来源
1. 使用配方文件(推荐)
# 当前目录查找 conanfile
$ conan install .
# 指定配方文件
$ conan install conanfile.py
$ conan install myfolder/ # 目录包含配方
2. 直接指定依赖(无需配方)
# 安装库依赖
$ conan install --requires=zlib/1.2.13 --requires=bzip2/1.0.8
# 安装工具依赖
$ conan install --tool-requires=cmake/3.23.5 --tool-requires=ninja/1.11.0
# 混合安装
$ conan install --requires=zlib/1.2.13 --tool-requires=ninja/1.11.0
最佳实践:建议使用
conanfile.py
管理依赖。
构建模式 (-b/--build
)
模式 | 说明 |
---|---|
--build=never | 禁止构建,仅使用二进制包(找不到则失败) |
--build=missing | 构建找不到二进制包的源码 |
--build=cascade | 构建至少有一个依赖需从源码构建的包(遗留模式,不推荐) |
--build=[pattern] | 构建包引用匹配模式的源码(支持 fnmatch 通配符,如 --build="zlib/*" ) |
--build=~[pattern] | 排除匹配模式的包(不构建) |
--build=missing:[pattern] | 仅为匹配模式的包构建缺失的二进制 |
--build=compatible:[pattern] | (实验性) 为匹配模式的包构建兼容的二进制 |
最佳实践:
- 避免使用
--build="*"
强制重建已有二进制- 推荐使用
--build=missing
或--build=missing:[pattern]
--build=cascade
仅用于特殊情况
生成器与部署器
生成器 (-g
)
$ conan install . -g CMakeDeps -g CMakeToolchain
作用:创建构建系统定位依赖所需的文件。
内置部署器 (-d
)
部署器 | 说明 |
---|---|
full_deploy | 完整复制所有依赖项到本地文件夹(避免冲突的目录结构) |
direct_deploy | 仅复制直接依赖项(不包括传递依赖) |
runtime_deploy | 部署所有共享库和可执行文件到扁平目录(Conan ≥2.5.0) |
包部署方法 (--deployer-package
)
# 执行所有包的 deploy() 方法
$ conan install . --deployer-package="*"
# 仅执行特定包的 deploy()
$ conan install . --deployer-package="pkg/*"
# 排除特定包
$ conan install . --deployer-package="*" --deployer-package="~zlib/*"
注意:部署到相同位置时需确保文件名不冲突(建议使用包名/版本创建子目录)。
锁文件管理
常用操作
# 使用默认锁文件 (conan.lock)
$ conan install .
# 允许部分依赖不在锁文件中
$ conan install . --lockfile-partial
# 生成更新后的锁文件
$ conan install . --lockfile-out=new.lock
# 清理未使用的条目
$ conan install . --lockfile-clean --lockfile-out=clean.lock
添加新依赖后更新锁文件
$ conan install . --lockfile-partial --lockfile-out=conan.lock
提示:复杂锁文件操作建议使用
conan lock
命令。
更新依赖 (-u/--update
)
# 更新所有依赖
$ conan install . --update
# 仅更新特定包
$ conan install . --update=openssl --update=boost
注意:会检查命令中指定的所有远程仓库。
关键流程
- 计算依赖图:
- 解析版本范围、条件依赖
- 应用配置文件、设置、选项
- 二进制评估:
- 检查本地缓存和远程仓库
- 根据
--build
模式决定构建策略
- 获取包:
- 下载二进制包
- 或按需从源码构建
- 后处理:
- 运行生成器创建文件
- 执行部署器复制文件
- 更新锁文件(如果指定)
最佳实践
- 依赖管理:
- 优先使用
conanfile.py
而非命令行直接指定依赖 - 在项目根目录使用标准名称
conanfile.py
- 优先使用
- 构建控制:
- 避免不必要的重建(谨慎使用
--build="*"
) - CI 流水线推荐
--build=missing
- 避免不必要的重建(谨慎使用
- 部署注意:
- 使用
full_deploy
进行完整依赖部署 - 使用
runtime_deploy
打包运行时依赖
- 使用
- 版本控制:
- 将
conan.lock
纳入版本控制确保一致性 - 使用
conan lock
命令管理复杂场景
- 将