Project examples as templates #78
Comments
I couldn't recall where I'd seen this to link at the time, but it just came up again: |
Using cargo generate --git <repo>#<sub-folder, this one 1) Allows to use a subfolder as the actual template (see #47) 2) Allows to e.g. generate a project from an example in a repo (see #78) 3) Avoids the conflicting requirements for cargo-generate#295 and cargo-generate#291, allowing for easier implementation of `--pick` for cargo-generate#291.
Using cargo generate --git <repo>#<sub-folder, this one 1) Allows to use a subfolder as the actual template (see #47) 2) Allows to e.g. generate a project from an example in a repo (see #78) 3) Avoids the conflicting requirements for cargo-generate#295 and cargo-generate#291, allowing for easier implementation of `--pick` for cargo-generate#291.
Using cargo generate --git <repo>#<sub-folder, this one 1) Allows to use a subfolder as the actual template (see #47) 2) Allows to e.g. generate a project from an example in a repo (see #78) 3) Avoids the conflicting requirements for cargo-generate#295 and cargo-generate#291, allowing for easier implementation of `--pick` for cargo-generate#291.
Using cargo generate --git <repo>#<sub-folder, this one 1) Allows to use a subfolder as the actual template (see #47) 2) Allows to e.g. generate a project from an example in a repo (see #78) 3) Avoids the conflicting requirements for cargo-generate#295 and cargo-generate#291, allowing for easier implementation of `--pick` for cargo-generate#291.
Using cargo generate --git <repo>#<sub-folder, this one 1) Allows to use a subfolder as the actual template (see #47) 2) Allows to e.g. generate a project from an example in a repo (see #78) 3) Avoids the conflicting requirements for cargo-generate#295 and cargo-generate#291, allowing for easier implementation of `--pick` for cargo-generate#291.
Using cargo generate --git <repo>#<sub-folder, this one 1) Allows to use a subfolder as the actual template (see #47) 2) Allows to e.g. generate a project from an example in a repo (see #78) 3) Avoids the conflicting requirements for cargo-generate#295 and cargo-generate#291, allowing for easier implementation of `--pick` for cargo-generate#291.
Using cargo generate --git <repo>#<sub-folder, this one 1) Allows to use a subfolder as the actual template (see #47) 2) Allows to e.g. generate a project from an example in a repo (see #78) 3) Avoids the conflicting requirements for cargo-generate#295 and cargo-generate#291, allowing for easier implementation of `--pick` for cargo-generate#291.
Using cargo generate --git <repo>#<sub-folder, this one 1) Allows to use a subfolder as the actual template (see #47) 2) Allows to e.g. generate a project from an example in a repo (see #78) 3) Avoids the conflicting requirements for cargo-generate#295 and cargo-generate#291, allowing for easier implementation of `--pick` for cargo-generate#291.
Using cargo generate --git <repo>#<sub-folder, this one 1) Allows to use a subfolder as the actual template (see #47) 2) Allows to e.g. generate a project from an example in a repo (see #78) 3) Avoids the conflicting requirements for #295 and #291, allowing for easier implementation of `--pick` for #291.
|
What's needed in order to close this? |
|
I wanted to start with an example folder to demonstrate certain use cases in order to provide some simple starting points for template authors. |
|
@sassman, I just added a folder cargo generate --git <repo>no matter where in the repo the templates are. I don't know if you've had time to look into #370, but that one should allow use to use github actions to expand, then compile-test the templates. I don't see how we could ever use regular examples as templates, as they simply do not contain the tags needed - thus it would end up being straight copies anyway, but #446 and #370 together will at least make it easy to expand embedded templates and help with the testability. |
|
@sassman what kind of examples should we provide in order to close this? |
In #47, one of the possibilities noted is
I wanted to make a suggestion that's a little more extensive than this, and I think it's enough of an expansion to list as a separate issue.
A number of projects have
examples/directories with cargo support for running them directly, and there's also a proposal to let cargo support larger per-directory examples in a sub-structure under there. These are often good starting points for customising your own code; I know I've done this a number of times, especially with some embedded projects. That sounds a lot like a template!I think is worth combining these proposals and having some specific conventions to make it easier, such that project example directories can always/automatically be templates. I'd like it to be sufficiently low-friction that neither general crate authors nor template consumers need to do anything much extra or unusual to use examples as templates, and offering templates becomes the norm.
This probably involves some changes on both sides, perhaps something like this:
example.tomlwith placeholder values. Cargo knows how to use this when running in-place as an example.cargo new --example?) so that there's a cohesive story from start to, well, new start :)cargo generatecan look in the examples directories to find templates, and (in interactive mode) offer a list to pick from, so that repos can be discoverable as either single templates at the root, or more structured collections.One of the strongest reasons for this is to keep examples and templates in sync with the libraries they represent; cargo should test each of the templates-as-examples just like today. If they're in a separate repo, there's always a risk they'll languish. If they're in the one repo, examples can also be updated to match library code changes on branches.
The text was updated successfully, but these errors were encountered: