RFC: Project-based Examples for Cargo Projects #2517

luojia65 · 2018-08-06T02:07:29Z

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 · 2018-08-06T19:55:09Z

text/0000-cargo-project-based-examples.md

+# Rationale and alternatives
+[rationale-and-alternatives]: #rationale-and-alternatives
+
+There could be another way to implement project-based examples by introducing `cargo example` subcommand. However by doing this we must change our way to run examples now by `cargo run --example <NAME>` which is already widely accepted by rust community. 


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.)

@killercup

Thank you @killercup

ehuss · 2018-08-06T23:19:45Z

text/0000-cargo-project-based-examples.md

+
+There could be another way to implement project-based examples by introducing `cargo example` subcommand. However by doing this we must change our way to run examples now by `cargo run --example <NAME>` which is already widely accepted by rust community. 
+
+It may also be suggested that we could somehow *not* implement this project-based cargo examples, but suggest the developers to build an example by adding all of them as the workspace members, and use the `cargo run -p <NAME>` command to run, test or bench it as it indicates the path of the root project, like what we already have in projects like [diesel] and [quicli]. By this way we share the `target` folder with the root project to improve compile speed as well as type less `cd` commands. However as we should add all our examples one by one into workspace if we do this, once we forget to add one newly-created example and users who does not know `cargo run -p` somehow run it by `cd examples/<NAME>` and `cargo run`, a huge `target` folder in the folder of the example would be created before being noticed. 


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 · 2018-08-07T05:08:51Z

text/0000-cargo-project-based-examples.md

+
+It may also be suggested that we could somehow *not* implement this project-based cargo examples, but suggest the developers to build an example by adding all of them as the workspace members, and use the `cargo run -p <NAME>` command to run, test or bench it as it indicates the path of the root project, like what we already have in projects like [diesel] and [quicli]. By this way we share the `target` folder with the root project to improve compile speed as well as type less `cd` commands, but we have to add all our examples one by one as subpackages into the workspace.
+
+[diesel]: https://github.com/diesel-rs/diesel/blob/master/Cargo.toml#L1-L26


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.

@killercup

Thanks to @killercup

tanriol · 2018-08-09T13:49:47Z

text/0000-cargo-project-based-examples.md

+
+There could be another way to implement project-based examples by introducing `cargo example` subcommand. However by doing this we must change our way to run examples now by `cargo run --example <NAME>` which is already widely accepted by rust community. 
+
+It may also be suggested that we could somehow *not* implement this project-based cargo examples, but suggest the developers to build an example by adding all of them as the workspace members, and use the `cargo run -p <NAME>` command to run, test or bench it as it indicates the path of the root project, like what we already have in projects like [diesel] and [quicli]. By this way we share the `target` folder with the root project to improve compile speed as well as type less `cd` commands, but we have to add all our examples one by one as subpackages into the workspace.


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

@tanriol

Thank you @tanriol

... so it would be easier to make inline comments.

tanriol · 2018-08-10T10:49:23Z

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 · 2018-08-13T21:44:05Z

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 · 2018-08-14T11:06:53Z

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?

This is really a test module, but the Rust convention is to put something like this under examples/, and when it lands, we can take advantage of "Project-based Examples for Cargo Projects" - RFC link at rust-lang/rfcs#2517

luojia65 · 2018-11-21T00:25:18Z

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

ehuss · 2019-09-21T00:42:23Z

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 · 2019-09-21T00:42:24Z

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

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 · 2019-09-21T13:42:46Z

@rfcbot reviewed

ExpHP · 2019-09-22T19:09:41Z

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 · 2019-09-23T14:17:16Z

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

rfcbot · 2019-10-03T14:22:07Z

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.

luojia65 added 2 commits August 1, 2018 11:51

RFC for cargo project-based examples

7e859cc

Minor modifications

de52fc2

Centril added the T-cargo Relevant to the Cargo team, which will review and decide on the RFC. label Aug 6, 2018

Oops

3ff812f

killercup reviewed Aug 6, 2018

View reviewed changes

luojia65 added 3 commits August 7, 2018 06:54

Add a paragraph for 'not implementing this'

18c95c4

Thank you @killercup

Minor modifications

764bf45

Ooops

0f3a1d0

ehuss reviewed Aug 6, 2018

View reviewed changes

Fixes. Thank you @ehuss

b44481b

killercup reviewed Aug 7, 2018

View reviewed changes

luojia65 added 2 commits August 7, 2018 14:17

Add commit hashs for all github urls

3eeebd2

Thanks to @killercup

--examples to test or bench all examples at one time

e3cdff1

tanriol reviewed Aug 9, 2018

View reviewed changes

luojia65 added 2 commits August 10, 2018 17:31

Add a way to auto-import subdirectories

a50092c

Thank you @tanriol

Have my paragraphs split

92df6cc

... so it would be easier to make inline comments.

konstin mentioned this pull request Aug 11, 2018

Initial datetime bindings PyO3/pyo3#200

Merged

Alternative: enhancing [[examples]]

fd3464a

luojia65 and others added 3 commits August 23, 2018 14:23

crates.io and one drawback, thanks to @chrysn

23ea734

Small fix

478330e

Consider build.rs file

1a46bb5

Centril added the A-examples Project examples related proposals & ideas label Nov 22, 2018

rfcbot added proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. disposition-close This RFC is in PFCP or FCP with a disposition to close it. labels Sep 21, 2019

rfcbot added final-comment-period Will be merged/postponed/closed in ~10 calendar days unless new substational objections are raised. and removed proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. labels Sep 23, 2019

rfcbot added the finished-final-comment-period The final comment period is finished for this RFC. label Oct 3, 2019

rfcbot added closed This FCP has been closed (as opposed to postponed) and removed final-comment-period Will be merged/postponed/closed in ~10 calendar days unless new substational objections are raised. disposition-close This RFC is in PFCP or FCP with a disposition to close it. labels Oct 3, 2019

rfcbot closed this Oct 3, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RFC: Project-based Examples for Cargo Projects #2517

RFC: Project-based Examples for Cargo Projects #2517

luojia65 commented Aug 6, 2018 •

edited

Loading

killercup Aug 6, 2018 •

edited

Loading

ehuss Aug 6, 2018

killercup left a comment

killercup Aug 7, 2018

tanriol Aug 9, 2018

tanriol commented Aug 10, 2018

ExpHP commented Aug 13, 2018

chrysn commented Aug 14, 2018

luojia65 commented Nov 21, 2018

ehuss commented Sep 21, 2019

rfcbot commented Sep 21, 2019 •

edited by nrc

Loading

Eh2406 commented Sep 21, 2019

ExpHP commented Sep 22, 2019

rfcbot commented Sep 23, 2019

rfcbot commented Oct 3, 2019


		There could be another way to implement project-based examples by introducing `cargo example` subcommand. However by doing this we must change our way to run examples now by `cargo run --example <NAME>` which is already widely accepted by rust community.

		It may also be suggested that we could somehow not implement this project-based cargo examples, but suggest the developers to build an example by adding all of them as the workspace members, and use the `cargo run -p <NAME>` command to run, test or bench it as it indicates the path of the root project, like what we already have in projects like [diesel] and [quicli]. By this way we share the `target` folder with the root project to improve compile speed as well as type less `cd` commands. However as we should add all our examples one by one into workspace if we do this, once we forget to add one newly-created example and users who does not know `cargo run -p` somehow run it by `cd examples/<NAME>` and `cargo run`, a huge `target` folder in the folder of the example would be created before being noticed.


		It may also be suggested that we could somehow not implement this project-based cargo examples, but suggest the developers to build an example by adding all of them as the workspace members, and use the `cargo run -p <NAME>` command to run, test or bench it as it indicates the path of the root project, like what we already have in projects like [diesel] and [quicli]. By this way we share the `target` folder with the root project to improve compile speed as well as type less `cd` commands, but we have to add all our examples one by one as subpackages into the workspace.

		[diesel]: https://github.com/diesel-rs/diesel/blob/master/Cargo.toml#L1-L26

RFC: Project-based Examples for Cargo Projects #2517

RFC: Project-based Examples for Cargo Projects #2517

Conversation

luojia65 commented Aug 6, 2018 • edited Loading

killercup Aug 6, 2018 • edited Loading

Choose a reason for hiding this comment

ehuss Aug 6, 2018

Choose a reason for hiding this comment

killercup left a comment

Choose a reason for hiding this comment

killercup Aug 7, 2018

Choose a reason for hiding this comment

tanriol Aug 9, 2018

Choose a reason for hiding this comment

tanriol commented Aug 10, 2018

ExpHP commented Aug 13, 2018

chrysn commented Aug 14, 2018

luojia65 commented Nov 21, 2018

ehuss commented Sep 21, 2019

rfcbot commented Sep 21, 2019 • edited by nrc Loading

Eh2406 commented Sep 21, 2019

ExpHP commented Sep 22, 2019

rfcbot commented Sep 23, 2019

rfcbot commented Oct 3, 2019

luojia65 commented Aug 6, 2018 •

edited

Loading

killercup Aug 6, 2018 •

edited

Loading

rfcbot commented Sep 21, 2019 •

edited by nrc

Loading