cargo-template

= cargo template :toc:

A utility for creating cargo projects from existing projects or templates

== Usage

The easiest way to install is through cargo install:

[source,bash]

$ cargo install cargo-template

After this you can create new rust projects this way:

[source,bash]

$ cargo template ~/path/to/my/template my-new-project

You can also use our template index if you don't have any templates locally:

[source,bash]

$ cargo template iron-basic my-new-iron-project

This requires an internet connection, and will put templates in ~/.cargo/cargo-template.

The index and templates get saved to your ~/.cargo directory, so if you know the template you want is in there, you can pass --frozen to cargo-template to ensure that it won't try to use the network.

One issue with using cargo install to install cargo-template is that we use cargo so that we can handle cargo config files in a consistent way. Unfortunately most of cargo is one big library, so we can't just pull in the cargo/config parts of it, we have to pull in & compile all of it. Since cargo install builds in --release mode, that means it takes a while to compile cargo. Hopefully one day cargo will be split up into smaller crates where possible.

== Configuration

By default, cargo-template will use our index, https://github.com/rusttemplates/templates.git. But this can be changed by editing your ~/.cargo/config file.

[source,toml]

[template.registry] index = "https://github.com/foo/bar"

== Caveats

Right now this is the absolute bare minimum I needed for this to work, so there are quite a few things missing, and there is bound to be bugs. PRs welcome!

== Contributing Templates

If you would like to contribute to template back to us, well, thanks! Here is how you can do that:

1. Fork & checkout the template registry, https://github.com/rusttemplates/templates
2. Open the index.json file, and in the index array, add an object that contains the name and loc (location) of your template.
3. Open a Pull Request back to the index
4. Bask in your awesomeness!