Support examples with their own Cargo.toml files

[jbethune]

Problem

The official package layout says that there can be an examples folder in a cargo package. This examples folder currently supports

1. examples/foo.rs standalone files
2. examples/foo/main.rs files in subfolders with supporting modules

I can compile and run these examples with

cargo run --example foo

However, some examples require a more complex setup. The examples folder of the axum project contains many subfolders and each subfolder contains a cargo package with a Cargo.toml.

It would be nice if cargo run --example foo supported a third case:

3. examples/foo/Cargo.toml should run the default binary from the cargo example package.

Proposed Solution

1. Implement support for finding examples with Cargo.toml files inside the examples folder
2. Easy solution: Automatically change into the directory of the examples crate and start a cargo run subprocess.

Notes

No response

[epage]

Could you go into more details about the underlying need?

You gave axum as an example but just said

However, some examples require a more complex setup

This leaves it to us to try to infer the intent and I didn't really see anything that required anything more.

It would also be good to discuss why axum's solution is insufficient. What is the difference between cargo run --example foo and cargo run --package example-foo?

One case I've heard is more clearly documenting examples / making it easier to copy examples out. One way of resolving that is to make examples also be cargo scripts. The manfiest would be unverified today but once we support cargo scripts in a workspace, you could have them both be an example and a workspace member.

My concern over the suggestion is that it changes the existing concept of workspace vs package vs build target and munges them together where you can have whole packages be build targets, acting kind of like a workspace but not.

[jbethune]

I like your suggestion with the cargo scripts solution. I know it is not ready yet, but from reading the RFCs, I can say that it would solve my issue.

Just a bit more background: I found it very confusing, that the axum project, which is a project by highly skilled rust programmers, is not able to have examples that run with cargo --example foo. I thought I was doing something wrong. But it seems that this is due to a limitation in Cargo and I expect that the axum project will probably also use cargo scripts for their examples in the future.

The issue can be closed. I'm looking forward to cargo scripts in the future.