- Feature Name: cargo-template
- Start Date: 28-03-2017
- RFC PR: (leave this empty)
- Rust Issue: (leave this empty)
Summary
This RFC proposes Cargo Templates to generate new projects from existing prototypes.
A simple version was already merged (but not released in Stable) without an RFC,
but some useful feedback has underlined the need to have more feedback in the
design phase.
Motivation
Writing boiler plate is no fun. Starting a new project often involves writing a
lot of repeated code, copying a LICENSE file into place, setting crate
dependencies, filling out a hello world example for the crate. In the case of a
daemon, setting up the main event loop and signal handling is also something
that requires filling out.
We propose Cargo Templates to generate new projects from existing prototypes.
This lets people start projects more quickly by not having to type out boiler
plate each time.
Also, because the templates can be managed as a repository, they can work as
way to spread up to date âbest practicesâ through curated templates.
Detailed design
The design of templates consists of two sides. The interface for users, and the
interface for template writers.
User Interface
Users creating a new project will use templates as follows:
$ cargo new foo --template https://gitrepo.com/user/rust-project-template
Template repositories may also have multiple templates within them. Therefore
you can specify a subdirectory: may also have sever
$ cargo new foo --template https://gitrepo.com/user/rust-project-templates --template-subdir cmdline
Templates can also be taken from file:// or from the local filesystem (using a
path). When using file:// or a path, it does not make sense to use
--template-subdir but it
Template Writer Interface
Templates will consist of two parts: a Template.toml file and the files
themselves. The Template.toml will consist of two parts: actions and
renames.
Actions
Templates actions consist of templating a file or copying a file into place.
Copying a file into place is used for binary blobs or files that do not need to
be templated (e.g. they may be templates themselves).
Renames
Renames are for files that conflict with files in the template. For example,
README.md and Template.toml (if you were to make a template of a template).
A rename entry is a list of <input-name> = output-name>
Example Template.toml
[actions]
template = ["src/main.rs", "src/cmd/new.rs"]
copy = [".travis.yml", "some-template.handlebars"]
[renames]
"README.md.in" = "README.md"
"Template.toml.in" = "Template.toml"
Template helpers
Some strings need to be escaped in different ways. For example a string in a
toml file needs \" when escaping quotes and nothing for <. But html uses
< for <. This is done by the template system with toml-escape and
html-escape:
[package]
name = "{{name}}"
version = "0.1.0"
authors = [{{toml-escape author}}]
Template strings
There are initially three template strings:
-
name : name of the project.
-
author: author of the project as retrieved from cargo settings or git
configuration.
-
date: used for injecting the date for e.g. copyright information into the
template.
How We Teach This
This should be documented in the crates.io documentation for the Cargo.toml
manifest format.
Drawbacks
This adds some complication into Cargo which could possibly be better suited to
an external tool, or one that is installed (e.g. clippy, etc).
Alternatives
Templating systems exist. They tend to be focused on their own language
communities. e.g. Cookiecutter
appears to focus on Python, while Boilr
appears to focus on Go.
Creating a template tool that works as a cargo subcommand which could be
installed. This is not in line one of the goals of discoverability as new users
who want to generate a hello world project would have no simple way to see that
the template subcommand exists. However, clippy surely has a dedicated
following.
We can use other template libraries. For example,
moustache or
Askama.
Unresolved questions
