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]

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

[ehuss]

We discussed this RFC in the Cargo team meeting, and have decided to move to close this. Although it can be nice to make it easier to create examples, we consider this a low priority and not worth the added complexity. Cargo workspaces provide a fairly equivalent, and more general solution. If there are ways that the workspace experience can be made smoother (such as rust-lang/cargo#5877 and rust-lang/cargo#5873), that might be a better alternative.

@rfcbot fcp close

[rfcbot]

Team member @ehuss has proposed to close this. The next step is review by the rest of the tagged team members:

• @Eh2406
• @alexcrichton
• @ehuss
• @joshtriplett
• @nrc
• @withoutboats

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[Eh2406]

@rfcbot reviewed

[ExpHP]

Hrm... I'm trying to remember now, wasn't there a similar proposal for tests? (I thought this was the one, but looking it over now it I see that it only describes examples).

For a while now I've been kind of just assuming that tests would eventually support Cargo projects and that this proposal (or whatever one it is that dealt with tests) was basically a shoe-in. :/

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to close, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

The RFC is now closed.