Support for examples (and tests?) at the workspace level

[mathstuf]

Describe the problem you are trying to solve
In the graphql-client set of crates, there is an examples directory at the workspace level. This keeps them visible and easy to find. However, they are not part of the cargo build --examples build at the top-level because they aren't found in the "right" location. CI ends up building them standalone which ends up causing lots of dependencies to be rebuilt again on top of the main workspace build set.

Describe the solution you'd like
It would be nice if something like this were possible:

[workspace]
examples = true

which would cause cargo to look in the examples/ directory for example (full crates I guess?) and merge them in with the main build set (if --examples or --all is in effect).

[ehuss]

Is there a reason you can't add the examples as workspace members? That would allow them to share the same artifacts with the other members. Also, if you place the examples' code in an examples directory, then you can do cargo build --examples at the root of the workspace and build all the examples at once. That is, an example could be something like graphql-client/examples/github/examples/query_repo.rs.

[mathstuf]

I think the main thing is that the examples are full crates which, AFAIK, is not supported in the examples directory today. Plus, one is a WASM test which…not sure how that'd work since it ends up as a cdylib crate type. The others look like they'd add significant crates to the dev-dependencies table if they were just examples.

I think adding them to the workspace is probably fine, but it'd be nice if they could be tagged as examples so they don't always build and are triggered by --examples.

[ehuss]

Each example can be a full package, with just one example per package, so they can each declare their own dependencies and whatnot. Like:

graphql-client/examples/github/Cargo.toml
graphql-client/examples/github/examples/github.rs
graphql-client/examples/hasura/Cargo.toml
graphql-client/examples/hasura/examples/hasura.rs
graphql-client/examples/web/Cargo.toml
graphql-client/examples/web/examples/web.rs

It is identical to your current layout, instead of placing them in the src directory you place the code in an examples directory. Examples can also specify a crate type, so the web example can still be a cdylib.

[mathstuf]

Hmm. If I move them, running cargo build --example hasura ends up with "no example target" error. Do they need to still be added to the workspace manually?

[mathstuf]

Hmm. I'm not seeing any documentation for how to specify an example as a full crate. Looking at cargo-metadata, I don't see a way to say the crate root in the [[example]] array; example.<name>.path seems to want to be a main.rs or lib.rs.

[ehuss]

They will need to be added to the workspace. One way is to add "examples/*" to the members list (and remove the workspace definition from each sub package).

To create a lib-based example, just explicitly define the example:

[[example]]
name = "myexample"
crate-type = ["cdylib"]

where myexample corresponds to examples/myexample.rs.

[mathstuf]

Ah, thanks, that clears it up. There is one thing that one example can't specify lto = "thin" since profiles are a workspace-wide thing, but I'll leave that as a comment for now.

[ehuss]

Yea, that's a bit unfortunate. There is the nightly-only profile overrides which provides a way to set the profile per-package. I'm hoping it will be on the path to stabilization soon.

[mathstuf]

Thanks for the pointers; this all seems to be working well enough for me now. I've added a comment to the cargo feature in the Cargo.toml for now. Thanks for the help!

[Jake-Shadle]

For anyone who finds this issue in the future, it should be noted that the layout described in #7467 (comment) will only work if you are using a virtual manifest, if you try the method in a workspace defined in a non-virtual manifest it will give the error: no example target named <name> error.

[jeffmo]

Wanted to add a note here since I banged my head on this for a minute while trying to add examples to my workspace:

In order to do this, AFAICT, you (1) must create a full crate for each of your workspace examples (i.e. you cannot create single-file examples for a workspace) and you (2) must place your example code into the /examples subdirectory of those example-crates (i.e. not in the src/ directory of those example-crates).

(point 2 is specified in @ehuss 's comment above above, I just skimmed too quickly and overlooked it thinking each example-crate specifies a src/main.rs).

So for clarity, my workspace dir:

$ ls
Cargo.lock
Cargo.toml
examples/
target/
terse_client/
terse_common/
terse_server/

My Cargo.toml:

[workspace]
members = [
  "terse_common",
  "terse_client",
  "terse_server",
  "examples/*",
]

And then my recursive examples/ dir:

$ ls examples/*/**
examples/client/Cargo.toml
examples/server/Cargo.toml

examples/client/examples:
client.rs

examples/server/examples:
server.rs

---

The 2 file structures I tried first which did not work as I'd initially assumed:
(i.e. cargo run --example client would not find the example)

1. myworkspace/examples/{client.rs,server.rs}
2. myworkspace/examples/client/{Cargo.toml,src/main.rs}

A general piece of feedback: It'd be nice if single-file examples worked for workspaces as they do for crates (e.g. myworkspace/examples/{client.rs,server.rs})

[aurexav]

For anyone who finds this issue in the future, it should be noted that the layout described in #7467 (comment) will only work if you are using a virtual manifest, if you try the method in a workspace defined in a non-virtual manifest it will give the error: no example target named <name> error.

I found this works without the requirement of the virtual manifest.

[[example]]
name = "xxx"
path = "examples/xxx/src/main.rs"

[nielsle]

For the sake of Google. Here is a nice example of a crate with grouped examples:

https://github.com/tracel-ai/burn/blob/main/Cargo.toml
https://github.com/tracel-ai/burn/tree/main/examples