Package scaffolding for conan new command

Warning

This functionality has to be considered as an experimental feature. We might change the context provided for these templates once we have more examples from the community.

Using the Conan command conan new is a very convenient way to start a new project with an example conanfile.py. This command has a --template argument that 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 the Conan cache templates containing not only a conanfile.py, but the full C++ project scaffolding. Thus just a single command can get you 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 also the paths to those files. Thus the following template directory (that does 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

Then the contents of all the files will be rendered using Jinja2 syntax as well, thus substituting content values with context values - as we will see in the next section.

Context

All the files should be valid Jinja2 templates. 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()

With the above template it’s now easy to overwrite such extra keywords with values from the command line:

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

Predefined templates

Available since: 1.40.0

The Conan client has some predefined templates that can be used with the command new. These two templates are related to Layouts and offer a simple Hello World example:

  • cmake_lib: Generates a hello world c++ library based on modern Conan recipe (layout + generate) using CMake as the build system.

  • cmake_exe: Generates a hello world executable based on modern Conan recipe (layout + generate) using CMake as the build system.

  • meson_lib: Generates a hello world c++ library based on modern Conan recipe (layout + generate) using Meson as the build system (since Conan 1.45).

  • meson_exe: Generates a hello world executable based on modern Conan recipe (layout + generate) using Meson as the build system (since Conan 1.45).

A full example can be found in Creating Packages section.