Skip to content
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

Closed
wants to merge 15 commits into from

Conversation

@luojia65
Copy link

commented Aug 6, 2018

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.

luojia65 added 2 commits Aug 1, 2018
@Centril Centril added the T-cargo label Aug 6, 2018
# 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.

This comment has been minimized.

Copy link
@killercup

killercup Aug 6, 2018

Member

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

luojia65 added 3 commits Aug 6, 2018
Thank you @killercup

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 comment has been minimized.

Copy link
@ehuss

ehuss Aug 6, 2018

Contributor

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.

Copy link
Member

left a comment

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

This comment has been minimized.

Copy link
@killercup

killercup Aug 7, 2018

Member

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.

luojia65 added 2 commits Aug 7, 2018
Thanks to @killercup

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.

This comment has been minimized.

Copy link
@tanriol

tanriol Aug 9, 2018

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

luojia65 added 2 commits Aug 10, 2018
Thank you @tanriol
... so it would be easier to make inline comments.
@tanriol

This comment has been minimized.

Copy link

commented Aug 10, 2018

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.

@konstin konstin referenced this pull request Aug 11, 2018
@ExpHP

This comment has been minimized.

Copy link

commented Aug 13, 2018

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

This comment has been minimized.

Copy link

commented Aug 14, 2018

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?

pganssle added a commit to pganssle/pyo3 that referenced this pull request Aug 21, 2018
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
pganssle added a commit to pganssle/pyo3 that referenced this pull request Aug 21, 2018
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
pganssle added a commit to pganssle/pyo3 that referenced this pull request Aug 21, 2018
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
pganssle added a commit to pganssle/pyo3 that referenced this pull request Aug 21, 2018
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
pganssle added a commit to pganssle/pyo3 that referenced this pull request Aug 21, 2018
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
pganssle added a commit to pganssle/pyo3 that referenced this pull request Aug 21, 2018
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 added 3 commits Aug 23, 2018
@luojia65

This comment has been minimized.

Copy link
Author

commented Nov 21, 2018

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

@Centril Centril added the A-examples label Nov 22, 2018
@ehuss

This comment has been minimized.

Copy link
Contributor

commented Sep 21, 2019

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

This comment has been minimized.

Copy link

commented Sep 21, 2019

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

This comment has been minimized.

Copy link

commented Sep 21, 2019

@rfcbot reviewed

@ExpHP

This comment has been minimized.

Copy link

commented Sep 22, 2019

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 comment has been minimized.

Copy link

commented Sep 23, 2019

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

@rfcbot

This comment has been minimized.

Copy link

commented Oct 3, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
9 participants
You can’t perform that action at this time.