Better organization for examples

[LennysLounge]

Problem

I have a crate with lots of examples and i want to be able to organize them by category.

Im writing a ui widget for egui and i have a few examples for that. I have examples that showcase the customization options and how to use them. I have examples that use and test some performance enhancing features of the widget. I also have some examples that i use to test some edge cases of the widget since testing ui's is tricky and its usually easier to setup an example for that specific test case.

I would like to organize those examples into those categories customization, performance and edge cases but as far as i am aware i cant.

There are only two ways i know of to add an example:

• As a foo.rs file directly in the /examples folder
• As a main.rs file in the /examples/foo folder

I cant add an example in a subfolder like this:

• As a foo.rs file directly in the /examples/bar folder
• As a main.rs file in the /examples/bar/foo folder

Proposed Solution

I would propose to also scan sub folder of /examples when scanning for available examples targets.

Those examples could the be availabe as targets folder.test-file or folder/testfile. The cargo command would then look like this cargo run --examples foo/test.

I dont know anything about the internals of cargo but i would assume that the algorithm for finding examples targets stays essentially the same, it just gets extended to sub directories as well.
Any .rs file that cargo finds while scanning /examples and its sub directories becomes an example target under its path + file name. If a folder contains a main.rs then the entire folder becomes one example target.

Notes

I stumbles across this issue #15324 which discusses axums use of examples here

When you turn an example into its own package its no longer compiled when running cargo test which might cause it to slowly rot and become incompatible with the main crate.
Its also less user friendly. I can no longer simply run cargo run --example foo from the main project directory. Instead you have to run cargo run --manifest-path ./examples/foo/Cargo.toml which just isn't very nice.

[epage]

Scanning subfolders would likely be a breaking and require an edition.

There would also need to be design on how to avoid ambiguity with examples/foo/main.rs and examples/foo/bar.rs on whether bar.rs is a submodule or different example.

/ and . are not a valid crate names. For whatever character is used, there is design work for dealing with ambiguities (the character being in the example name or created due to a subfolder).

As a workaround, you can manually specify each example in these subfolders.

[LennysLounge]

As a workaround, you can manually specify each example in these subfolders.

Can you tell me a little more about this. I dont think i know what you mean.

[weihanglo]

As a workaround, you can manually specify each example in these subfolders.

Can you tell me a little more about this. I dont think i know what you mean.

See https://doc.rust-lang.org/nightly/cargo/reference/cargo-targets.html#the-path-field, for example:

[[example]]
name = "foo"
path = "path/to/file.rs"