conan new¶
从预定义或用户定义的模板创建一个新的 recipe(包含 conanfile.py 和其他相关文件)。
conan new¶
$ conan new -h
usage: conan new [-h] [-v [V]] [-cc CORE_CONF] [--out-file OUT_FILE]
[-d DEFINE] [-f] [-o OUTPUT]
template
Create a new example recipe and source files from a template.
positional arguments:
template Template name, either a predefined built-in or a user-
provided one. Available built-in templates: basic,
cmake_lib, cmake_exe, meson_lib, meson_exe,
msbuild_lib, msbuild_exe, bazel_lib, bazel_exe,
autotools_lib, autotools_exe, local_recipes_index,
workspace. E.g. 'conan new cmake_lib -d name=hello -d
version=0.1'. You can define your own templates too by
inputting an absolute path as your template, or a path
relative to your conan home folder.
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
--out-file OUT_FILE Write the output of the command to the specified file
instead of stdout.
-d DEFINE, --define DEFINE
Define a template argument as key=value, e.g., -d
name=mypkg
-f, --force Overwrite file if it already exists
-o OUTPUT, --output OUTPUT
Output folder for the generated files
conan new
命令在当前工作目录中创建一个新的 recipe,外加额外的示例文件,例如 CMakeLists.txt 或 test_package 文件夹(根据需要),可以用作您自己项目的基础或辅助调试过程。
请注意,每个模板都有一些必需的和一些[可选的]用户定义的变量,用于自定义生成的文件。
可用的模板有
basic:创建一个简单的 recipe,其中包含一些示例代码和有用的注释,是避免编写样板代码的良好起点。
其变量为:[name]、[version]、[description]、[requires1, requires2, …]、[tool_requires1, tool_requires2, …]
alias:创建定义目标 recipe 别名所需的最少 recipe
其变量为:name、[version]、target
cmake_lib:创建一个 cmake 库目标,该目标定义一个名为
name
的函数,该函数会将有关编译环境的一些信息打印到 stdout。您可以以以下形式向此模板添加 requirementsconan new cmake_lib -d name=ai -d version=1.0 -d requires=math/3.14 -d requires=magic/0.0
这将为 requirements() 方法添加
math/3.14
和magic/0.0
的 requirements,将在 CMake 中添加必要的find_package
,并在生成的ai()
函数内添加对math()
和magic()
的调用。其变量为:name、version、[requires1, requires2, …]、[tool_requires1, tool_requires2, …]
cmake_exe:创建一个 cmake 可执行目标,该目标定义一个名为
name
的函数,该函数会将有关编译环境的一些信息打印到 stdout。您可以以以下形式向此模板添加 requirementsconan new cmake_exe -d name=game -d version=1.0 -d requires=math/3.14 -d requires=ai/1.0
这将为 requirements() 方法添加
math/3.14
和ai/1.0
的 requirements,将在 CMake 中添加必要的find_package
,并在生成的game()
函数内添加对math()
和ai()
的调用。其变量为:name、version、[requires1, requires2, …]、[tool_requires1, tool_requires2, …]
autotools_lib:创建一个 Autotools 库。
其变量为:
name
、version
autotools_exe:创建一个 Autotools 可执行文件
其变量为:
name
、version
bazel_lib:Bazel 集成 BazelDeps、BazelToolchain、Bazel 处于实验阶段。创建一个 Bazel 库。
其变量为:
name
、version
bazel_exe:Bazel 集成 BazelDeps、BazelToolchain、Bazel 处于实验阶段。创建一个 Bazel 可执行文件
其变量为:
name
、version
meson_lib:创建一个 Meson 库。
其变量为:
name
、version
meson_exe:创建一个 Meson 可执行文件
其变量为:
name
、version
msbuild_lib:创建一个 MSBuild 库。
其变量为:
name
、version
msbuild_exe:创建一个 MSBuild 可执行文件
其变量为:
name
、version
默认情况下,如果用户未提供,所有 name
和 version
变量分别设置为 mypkg
和 0.1
。
警告
预定义的内置模板的输出是不稳定的。它可能会在未来的版本中更改,以适应最新的工具或良好实践。
示例¶
$ conan new basic
生成一个基本的 conanfile.py,它不实现任何自定义功能
$ conan new basic -d name=mygame -d requires=math/1.0 -d requires=ai/1.3
为依赖于包 math/1.0
和 ai/1.3
的 mygame
生成 conanfile.py
$ conan new cmake_lib
创建一个基本的 CMake 库,默认包 name = "mypkg"
和默认包版本 version = "0.1"
$ conan new cmake_exe -d name=game -d version=1.0 -d requires=math/3.14 -d requires=ai/1.0
为 CMake 可执行目标生成必要的文件。这将为 requirements()
方法添加 math/3.14
和 ai/1.0
的 requirements,将在 CMake 中添加必要的 find_package
,并在生成的 game()
函数内添加对 math()
和 ai()
的调用。
自定义模板¶
还可以创建您自己的模板。Conan home 中的模板应位于 templates/command/new
文件夹中,每个模板都应有一个以模板名称命名的文件夹。如果我们创建 templates/command/new/mytemplate
文件夹,则可以使用以下命令调用该模板
$ conan new mytemplate
与 Conan home 中的其他文件一样,您可以使用 conan config install <url>
管理这些模板,将它们放在 git 仓库或 http 服务器中,并与您的团队共享。也可以使用任何文件夹中的模板,只需在 conan new <full_path>
中传递模板的完整路径,但通常在 Conan home 中管理它们更方便。
该文件夹可以包含任意数量的文件。文件名和文件内容都可以使用 Jinja2 语法进行模板化。-d/--define
参数将定义模板的 key=value
输入。
文件内容将如下所示(Jinja2 语法)
# File "templates/command/new/mytemplate/conanfile.py"
from conan import ConanFile
class Conan(ConanFile):
name = "{{name}}"
version = "{{version}}"
license = "{{license}}"
它将需要传递这些值
$ conan new mytemplate -d name=pkg -d version=0.1 -d license=MIT
它将在当前文件夹中生成一个文件
# File "<cwd>/conanfile.py"
from conan import ConanFile
class Conan(ConanFile):
name = "pkg"
version = "0.1"
license = "MIT"
有一些特殊的 -d/--defines
名称。name
是始终强制性的。conan_version
定义将始终自动定义。requires
和 tool_requires
定义(如果存在)将自动转换为列表。package_name
将始终被定义,默认情况下等于 name
。
对于参数化的文件名,文件名本身支持 Jinja2 语法。例如,如果我们在模板文件夹 templates/command/new/mytemplate/
中存储一个字面名为 {{name}}
的文件,而不是上面的 conanfile.py
{{contents}}
那么,执行
$ conan new mytemplate -d name=file.txt -d contents=hello!
将在当前目录中创建一个名为 file.txt
的文件,其中包含字符串 hello!
。
如果模板中有一些文件不需要使用 Jinja2 渲染,例如图像文件,则应将它们的名字添加到模板目录中名为 not_templates
的文件中,每行一个文件名。因此,我们可能有一个包含以下内容的文件夹
templates/command/new/mytemplate
|- not_templates
|- conanfile.py
|- image.png
|- image2.png
并且 not_templates
包含字符串 *.png
,那么 conan new mytemplate ...
将仅通过 Jinja2 渲染 conanfile.py
,但两个图像都将按原样复制。