Proposal: re-organize examples to contain their own target and dependencies

[apullin]

Currently, the dependencies are tied to the target-triple in freertos-rust-examples/Cargo.toml, and the build.rs ties example paths directly to targets.

After some tinkering with cargo, it seems there might not be a way to improve on this.

However, if each "example" is reorganized into its own cargo binary project, then:

• the target triple can be put into .cargo/config.toml for each
• dependencies for each can be made unique
• build.rs does not need to link targets to example paths

proposed reorg here:
https://github.com/apullin/FreeRTOS-rust/tree/examples_reorg/freertos-rust-examples/examples/stm32f407-segger-trace

This might be moot, since the "examples" should just be templates, and any new project would have a project-specific build.rs and config.toml anyway.

However, this way, each refactored example would be a template to copy & adapt directly (just paths, I think?) for new projects.

[schteve]

I agree it would be nice to have each example be a kind of standalone template for the situation it is illustrating. It's not clear to me that the overhead of making, essentially, a separate project for each example is worth it though. For example the current setup leverages cargo's example system, so you can build / run each one like cargo run --example win. As far as I can tell (correct me if you know better), putting each example into a separate project means this doesn't work anymore. It's not critical of course but is helpful, especially to easily verify that all examples build correctly (cargo build --examples).

Personally I think the current system with build.rs and Cargo.toml managing all examples isn't too hard to follow and adapt. I agree that it would be better to not tie each example to the target so it would be possible to have multiple examples for the same architecture. I wonder if there is some other way to select each example without using the target.

Looking at the examples project the readme gives detailed instructions on how to setup and run the examples. How much of this readme would be unnecessary if each example were separate? For example setting rustup defaults and targets I think can be set in the rust-toolchain.toml which would be very helpful. Or, the remaining parts specific to each example could be put in each example's readme.

[schteve]

Sorry it took so long to get back to this. As part of verifying the fix for #36, I've had a lot of trouble getting the individual examples to build - currently, none of them successfully build for me. For most of the examples I'm not sure if it's something on my end or if the examples themselves are broken. With all of this trouble it's apparent that some trouble comes from the mix of targets and toolchains required for each example, which I think would be significantly easier to manage with your proposed reorganization. Having an individual .cargo/config, rust-toolchain.toml in particular.

One thing I noted when playing with workspace organization is that, in a workspace, only the workspace-level .cargo/config is used. Cargo will look at the workspace level for it and ignore any in each of the individual crates. Thus to make each example work as expected we may need to also remove the example crate from the workspace (leaving only freertos-cargo-build and freertos-rust). I'm not sure if there's any other side effects of this though.

[apullin]

That very problem is why I though to re-organize them ... but it's an incomplete concept.
Ideally, we'd have some paradigm for a CSP package and a BSP package, and each example would be some platform-agnostic demonstration of how to use a Semaphore, a Task from a closure, etc etc.

It really does not seem like cargo has the feature(s) we need to do this ... although it is full of small, barely-documented stuff, like the rust-toolchain.toml trick you mentioned above.

For doing some other dev work on this repo, I now just use a separate project that references this crate by path, so I am totally outside of the "examples" framework. But that doesn't solve the "examples" issue.

Really not sure how to overcome this ...

[schteve]

Yeah, it all depends how far the examples should go. I'm not sure that it's feasible to have an example for every feature of the crate across all platforms (or, it's more work than I want to put in - maybe someone else does 😄). Maybe it's enough to illustrate a few common features and also running the RTOS on a few platforms. And as you said if it could serve as a starter template for other projects on the same platform that would be great.

To me it seems there are 3 main purposes for examples here:

1. Show off the features of the crate and how to use them (Task, Queues, Semaphores, etc).
2. Have ready-to-run packages that new users can try out to see that it works in practice, if they have the same platform.
3. Act as starter template for new projects on the same platform.

• 1 needs more work, since the current examples focus on Task (or a single task) right now. But reorganizing doesn't help this.
• 2 and 3 would benefit a lot from improved organization like what you proposed. So I think it's reasonable to go forward with something on this front.

Also one small issue is that I don't currently have hardware to run all of the examples to verify that they run correctly. I can verify building but not running.

[niondir]

Interesting discussion.
For me, initially, the examples helped to get "something" running in the hardware I had available. There is no deeper purpose yet.

External projects that demo the usage for single toolchains and target's might be a good option, I would call them "templates" to not confuse with Cargo example mechanisms. We can even Link them in the readme and they can have different maintainers. If needed we could create a separate organisation later.

As purpose to demonstrate features of the crate it might be enough to have examples that run on windows & Linux. That might keep them better maintainable.

But without digging into cargo Details (not working with it on a daily base) I can't come up with than this thoughts.