How to include example projects in workspaces

help
1

Hi Community,

I have a problem with cargo finding examples in a workspace.

My Workspace layout is basically the following:

.
├── project1
│   ├── Cargo.toml
│   ├── examples
│   │   └── ok-example.rs
│   └── src
│   │   ├── lib.rs
│   │   └── main.rs
├── project2
│   ├── Cargo.toml
│   ├── examples
│   │   ├── another-ok-example.rs
│   │   ├── problematic-example
│   │   │   ├── Cargo.toml
│   │   │   └── src
│   │   │       └── main.rs
│   ├── src
│   │   ├── lib.rs
│   │   └── main.rs
├── Cargo.lock
├── Cargo.toml
└── rust-toolchain.toml

Now, when I run cargo run --examples it recognizes only ok-example and another-ok-example as valid examples but does not list problematic-example.

I tried adding problematic-example as a workspace member in the workspaces Cargo.toml and/or creating an empty workspace section within the Cargo.toml of the example. Sadly without success.

Creating an "examples" folder in the workspace root and putting the example there didn't work either.

I am currently using: cargo 1.85.0-nightly (4c39aaff6 2024-11-25)

What is the correct way to include example projects (not just simple files) in a workspace?

2

Examples don't have manifest files. What does the Cargo.toml file in your problematic-example do? If all it does is define some extra dependencies, add them as [dev-dependencies] to your project2/Cargo.toml instead and remove project2/examples/problematic-example/Cargo.toml.

If you really need to have your example be a package on its own while maintaining the ability to run it as an example inside of your workspace, making problematic-example a workspace member and overriding Cargo's target auto-discovery by modifying its Cargo.toml file like this:

[package]
autobins = false

[[example]]
name = "problematic-example"
path = "src/main.rs"

should probably do the trick (untested).

1 Like
3

Hi Jofas,

thanks for your fast reply :+1:

I was unaware that examples are just simple files and cannot be a full cargo package. (I thought I saw it somewhere, but I must be mistaken. :person_shrugging:)

The main reason I wanted a Cargo.toml was to specify dependencies for this specific example and leave the dev-dependencies for the main package untouched. But this seems to be the correct way to go. :smile:

4

That's not improbable. But if you want or need truly stand-alone examples that have their own package, you usually also treat these examples as a package with a binary target. At least as far as what I've seen in the ecosystem (see i.e. the actix examples workspace). The downside with this is what you described in your OP, the --examples target selector doesn't pick these packages up as examples.

5

That's a choice of the author, not necessary, though; a package containing one example target is just as valid as a package containing one bin target.