Package scaffolding for conan new command

Warning

This has to be an considered as an experimental feature, we might change the context provided to this templates once we have more exmpales from the community.

Using the Conan command conan new is a very convenient way to start a new project with a example conanfile.py. This command has a --template argument you can use to provide a path to a template file for the conanfile.py itself or even a path to a folder containing files for a C++ project using Conan recipes.

The argument --template can take an absolute path or a relative path. If relative, Conan will look for the files starting in the Conan cache folder templates/command/new/, this is very useful in combination with conan config install because you can easily share these templates with all your team.

Note

For backwards compatibility reasons, if the --template argument takes the path to a single file Conan will look for it in the cache at the path templates/<filename> first. This will likely be removed in Conan v2.0

This mechanism lets you have in the Conan cache templates containing not only a conanfile.py, but the full C++ project scaffolding, and with a single command you can get started:

$ conan new mypackage/version --template=header_only
$ conan new mypackage/version --template=conan-center

Conan will process all the files found in that folder using Jinja2 engine and the paths to those files too. Thus the following template directory (which match the conventions for conan-center-index recipes):

conan-center/{{name}}/config.yml
            /{{name}}/all/conanfile.py
            /{{name}}/all/conandata.yml
            /{{name}}/all/test_package/conanfile.py
            /{{name}}/all/test_package/CMakeLists.txt
            /{{name}}/all/test_package/main.cpp

will be translated to:

conan-center/mypackage/config.yml
            /mypackage/all/conanfile.py
            /mypackage/all/conandata.yml
            /mypackage/all/test_package/conanfile.py
            /mypackage/all/test_package/CMakeLists.txt
            /mypackage/all/test_package/main.cpp

And the contents of all the files will be rendered using Jinja2 syntax too, substituting values in the context as we will see in the next section.

Context

All the files should be valid Jinja2 templates and they will be feed with the following context:

name and version: defined from the command line.
package_name: a CamelCase variant of the name. Any valid Conan package name like package_name, package+name, package.name or package-name will be converted into a suitable name for a Python class, PackageName.
conan_version: an object that renders as the current Conan version, e.g. 1.24.0.

Example

This is a very simple example for a header only library:

# Recipe autogenerated with Conan {{ conan_version }} using `conan new --template` command

from conans import ConanFile


class {{package_name}}Conan(ConanFile):
    name = "{{ name }}"
    version = "{{ version }}"
    settings = "os", "arch", "compiler", "build_type"
    exports_sources = "include/*"

    def package(self):
        self.copy("*.hpp", dst="include")
        self.copy("LICENSE.txt", dst="licenses")

    def package_id(self):
        self.info.header_only()

Custom definitions

Sometimes it’s needed to provide additional variables for the custom templates. For instance, if it’s desired to have description and homepage to be templated as well:

# Recipe autogenerated with Conan {{ conan_version }} using `conan new --template` command

from conans import ConanFile


class {{package_name}}Conan(ConanFile):
    name = "{{ name }}"
    version = "{{ version }}"
    description = "{{ description }}"
    homepage = "{{ homepage }}"
    settings = "os", "arch", "compiler", "build_type"
    exports_sources = "include/*"

    def package(self):
        self.copy("*.hpp", dst="include")
        self.copy("LICENSE.txt", dst="licenses")

    def package_id(self):
        self.info.header_only()

now it’s easy to overwrite these values from the command line:

$ conan new mypackage/version --template=header_only -d homepage=https://www.example.com -d description="the best package"