cargo-generate

cargo, make me a project

cargo-generate is a developer tool to help you get up and running quickly with a new Rust project by leveraging a pre-existing git repository as a template.

Here's an example of using cargo-generate with this template:

Installation

Using `cargo` with system's OpenSSL

cargo install cargo-generate

See the openssl-sys crate readme on how to obtain the OpenSSL library for your system. Alternatively, use the vendored-openssl flag if you do not want to install OpenSSL.

Using `cargo` with vendored OpenSSL

cargo install cargo-generate --features vendored-openssl

Manual Install:

Download the binary tarball for your platform from our releases page.
Unpack the tarball and place the binary cargo-generate in ~/.cargo/bin/

Usage

Standard usage is to pass a --git flag to cargo generate or short cargo gen. This will prompt you to enter the name of your project.

NOTE: cargo gen requires an cargo alias configuration

cargo generate --git https://github.com/githubusername/mytemplate.git

You can also pass the name of your project to the tool using the --name or -n flag:

cargo generate --git https://github.com/githubusername/mytemplate.git --name myproject

Favorites

Favorite templates can be defined in a config file, that by default is placed at $CARGO_HOME/cargo-generate. To specify an alternative configuration file, use the --config <config-file> option.

Each favorite template is specified in its own section, e.g.:

[favorites.demo]
description = "Demo template for cargo-generate"
git = "https://github.com/ashleygwilliams/wasm-pack-template"
branch = "master"

Both branch and description are optional, and the branch may be overridden by specifying --branch <branch> on the command line.

When favorites are available, they can be generated simply by invoking:

cargo gen <favorite>

or slightly more involved:

cargo generate demo --branch master --name expanded_demo

NOTE: when <favorite> is not defined in the config file, it is interpreted as a git repo like as if --git <favorite>

Templates

Templates are git repositories whose files contain placeholders. The current supported placeholders are:

{{authors}}: this will be filled in by a function borrowed from Cargo's source code, that determines your information from Cargo's configuration.
{{project-name}}: this is supplied by either passing the --name flag to the command or working with the interactive CLI to supply a name.
{{crate_name}}: the snake_case_version of project-name
{{os-arch}}: contains the current operating system and architecture ex: linux-x86_64

Additionally all filters and tags of the liquid template language are supported. For more information, check out the Liquid Documentation on Tags and Filters.

You can also add a .genignore file to your template. The files listed in the .genignore file will be removed from the local machine when cargo-generate is run on the end user's machine. The .genignore file is always ignored, so there is no need to list it in the .genignore file.

Here's a list of currently available templates. If you have a great template that you'd like to feature here, please file an issue or a PR!

Template defined placeholders

Sometimes templates need to make decisions. For example one might want to conditionally include some code or not. Another use case might be that the user of a template should be able to choose out of provided options in an interactive way. Also it might be helpful to offer a reasonable default value that the user just simply can use.

Since version 0.6.0 it is possible to use placeholders in a cargo-generate.toml that is in the root folder of a template.
Here an example:

[placeholders.hypervisor]
type = "string"
prompt = "What hypervisor to use?"
choices = ["uhyve", "qemu"]
default = "qemu"

[placeholders.network_enabled]
type = "bool"
prompt = "Want to enable network?"
default = true

As you can see the placeholders configuration section accepts a table of keywords that will become the placeholder name.

In this example the placeholder hypervisor and network_enabled will become template variables and can be used like this:

{% if network_enabled %}
use std::net::TcpListener;

fn main() {
    let listener = TcpListener::bind("0.0.0.0:8080").unwrap();
    loop {
        let (conn, addr) = listener.accept().unwrap();
        println!("Incoming Connection from {}", addr);
        std::io::copy(&mut &conn, &mut &conn).unwrap();
    }
}
{% else %}
fn main() {
    println!("Hello Rusty Hermit 🦀");
}
{% endif %}

Tip: similar to dependencies in the Cargo.toml file you can also list them as one liners:

[placeholders]
hypervisor = { type = "string", prompt = "What hypervisor to use?", choices = ["uhyve", "qemu"], default = "qemu" }
network_enabled = { type = "bool", prompt = "Want to enable network?", default = true }

`prompt` property

The prompt will be used to display a question / message for this very placeholder on the interactive dialog when using the template.

🤷  What hypervisor to use? [uhyve, qemu] [default: qemu]:

`type` property

A placeholder can be of type string or bool. Boolean types are usually helpful for conditionally behaviour in templates.

`choices` property (optional)

A placeholder can come with a list of choices that the user can choose from. It's further also validated at the time when a user generates a project from a template.

choices = ["uhyve", "qemu"]

`default` property (optional)

A default property must mach the type (string | bool) and is optional. A default should be provided, to ease the interactive process. As usual the user could press and the default value would simply be taken, it safes time and mental load.

default = 'qemu'

`regex` property (optional)

A regex property is a string, that can be used to enforce a certain validation rule. The input dialog will keep repeating until the user entered something that is allowed by this regex.

Placeholder Examples

An example with a regex that allows only numbers

[placeholders]
phone_number = { type = "string", prompt = "What's your phone number?", regex = "[0-9]+" }

Default values for placeholders from a file

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]
hypervisor = "qemu"
network_enabled = true

Include / Exclude

Templates support a cargo-generate.toml, with a "template" section that allows you to configure the files that will be processed by cargo-generate. The behavior mirrors Cargo's Include / Exclude functionality, which is documented here. If you are using placeholders in a file name, and also wish to use placeholders in the contents of that file, you should setup your globs to match on the pre-rename filename.

[template]
include = ["Cargo.toml"]
# include and exclude are exclusive, if both appear we will use include
exclude = ["*.c"]

Cargo gen - alias

cargo gen requires an cargo alias to be configured in your $HOME/.cargo/config like this:

[alias]
gen = "generate"

License

Licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. If you want to contribute to cargo-generate, please read our CONTRIBUTING notes.

cargo-generate 0.6.1