= 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.json
file, and in theindex
array, add an object that contains thename
andloc
(location) of your template. - Open a Pull Request back to the index
- Bask in your awesomeness!