RFC: Project-based Examples for Cargo Projects

[luojia65]

This RFC enables cargo to run, test or bench examples which are arranged and stored as a project-based cargo project in examples folder. A project-based example imply a complete cargo project with Cargo.toml, src folder, main.rs, build script like build.rs and maybe other necessary files in it.

For example, by using a simple command cargo new --example abc, you can create an example named abc for your project, which has this folder structure after creation:

.
├── Cargo.lock
├── Cargo.toml
├── src
│   └── lib.rs 
└── examples 
    └── abc # created by the command
        ├── Cargo.lock 
        ├── Cargo.toml # import your crates here
        └── src
            └── main.rs # write your example code here

And, as well, you may conveniently run this example using cargo run --example abc, the same command as what you use now.

Rendered

Discussion on Internals

Thanks to @Nemo157, @thomwiggers, @chrysn, @ehuss for suggestions and ideas.

[killercup]

Sorry, I'll be devil's advocate here for a bit.

Another (valid but boring) alternative: Change nothing but actively tell people not to use cargo run --example in some cases. You can use cargo's workspace feature to use a common target directly (faster compile times), and just run cargo commands in the subdirectory. This is what diesel and quicli do. This also allows you to have multiple binaries in your example projects, as well as using your shell prompt's path printing feature as an indicator for the current example project context.

(I'm pretty sure this was already mentioned somewhere but I feel like it should also be listed in this section.)

[ehuss]

This isn't quite correct. Once you have a workspace, if you forget to add a new sub-package to the members list, it will refuse to compile. cargo new will also yell at you so you don't forget.

[killercup]

Thanks for the update!

Random other things/tip for your next RFC: It's much easier to add useful inline comments if you split your paragraphs over multiple lines :) http://rhodesmill.org/brandon/2012/one-sentence-per-line/

[killercup]

Thanks for the update!

Random other things/tip for your next RFC: It's much easier to add useful inline comments if you split your paragraphs over multiple lines :) http://rhodesmill.org/brandon/2012/one-sentence-per-line/

[killercup]

You should always use Github URLs containing the commit hash, otherwise the content will change and the highlighted lines will point to something totally different. You can easy get that by pressing y on any source page on Github.

[tanriol]

Sub-alternative: automatically add projects in examples/ to the workspace, just like path dependencies are auto-added.

[tanriol]

Do you expect the examples to be considered workspace members? If they are, they share the same Cargo.lock as the other members, so nothing needs to be done to .gitignore.

[ExpHP]

Nit: src/main.rs cannot/should not be required, because Cargo.toml can set an arbitrary path for the main module. I think the deciding factor should be "a subdirectory of examples/ with a Cargo.toml".

Related thought: It would be interesting if an explicit [[examples]] entry could directly specify a path to a Cargo.toml (in addition to the existing alternative of a rust source file or a directory).

[chrysn]

How would crates.io treat those examples? Right now, with example dependencies in dev-dependencies, I can find examples of how linux-embedded-hal is used easily. How would the proposal affect that?

[luojia65]

Edit: consider build.rs, I've done minor modifications