Crate cargo_generate[−][src]

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.

Macros

info

Structs

Args

Enums

Cli
Vcs

Functions

generate