-
Notifications
You must be signed in to change notification settings - Fork 1.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
RFC: Project-based Examples for Cargo Projects #2517
Conversation
# 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.)
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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/
|
||
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sub-alternative: automatically add projects in examples/
to the workspace, just like path dependencies are auto-added.
... so it would be easier to make inline comments.
Do you expect the examples to be considered workspace members? If they are, they share the same |
Nit: Related thought: It would be interesting if an explicit |
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
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
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
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
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
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
Edit: consider |
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 |
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. |
@rfcbot reviewed |
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. :/ |
🔔 This is now entering its final comment period, as per the review above. 🔔 |
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. |
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 withCargo.toml
,src
folder,main.rs
, build script likebuild.rs
and maybe other necessary files in it.For example, by using a simple command
cargo new --example abc
, you can create an example namedabc
for your project, which has this folder structure after creation: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.