= 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:
- Fork & checkout the template registry,
https://github.com/rusttemplates/templates - Open the
index.jsonfile, and in theindexarray, add an object that contains thenameandloc(location) of your template. - Open a Pull Request back to the index
- Bask in your awesomeness!