Crate cargo_generate[−][src]
Expand description
Generate a new Cargo project from a given template
Right now, only git repositories can be used as templates. Just execute
$ cargo generate –git https://github.com/user/template.git –name foo
or
$ cargo gen –git https://github.com/user/template.git –name foo
and a new Cargo project called foo will be generated.
TEMPLATES:
In templates, the following placeholders can be used:
-
project-name: Name of the project, in dash-case -
crate_name: Name of the project, but in a case valid for a Rust identifier, i.e., snake_case -
authors: Author names, taken from usual environment variables (i.e. those which are also used by Cargo and git)
The template author can define their own placeholders in their
cargo-generate.toml file. This looks like the following:
[placeholders]
my-placeholder = { type = "string", prompt = "Hello?", choices = ["hello", "world"], default = "hello", regex = "*" }
use-serde = { type = "bool", prompt = "Add serde support?", default = false }
The user of the template will then be asked the the question in “prompt”, and must accept the default value (if provided) or enter a custom value which will be checked against “choices” (if provided) and regex (if provided).
The placeholder map supports the following keys:
type (required): Must be “string” or “bool”
prompt (required): A string containing the question to be asked to the user
default (optional): The default value to be used if the user just presses enter. Must be
consistent with type
choices (optional; string only): Possible values the user may enter
regex (optional; string only): Regex to validate the entered string
For automation purposes the user of the template may provide provide a file containing the
values for the keys in the template by using the --template-values-file flag.
The file should be a toml file containing the following (for the example template provided above):
[values] my-placeholder = "world" use-serde = true
If a key is missing in this file, the user will be requested to provide the entry manually. If a key in this file is not part of the original template it will be ignored.
To ensure that no interaction will be requested to the user use the --silent flag. Then, if a
template key is missing an error will be returned and the project generation will fail.
Notice: project-name and crate_name can’t be overriden through this file and must be
provided through the --name flag.
os-arch and authors also can’t be overriden and are derived from the environment.