116 lines
5.6 KiB
Plaintext
116 lines
5.6 KiB
Plaintext
+++
|
|
title = "Rust Embedded Unit Testing"
|
|
date = 2023-10-28T18:41:37-05:00
|
|
draft = false
|
|
+++
|
|
:caution-caption: pass:[<span style="font-size: 2em">☠</span>]
|
|
:important-caption: pass:[<span style="font-size: 2em">❗</span>]
|
|
:note-caption: pass:[<span style="font-size: 2em">✏️</span>]
|
|
:tip-caption: pass:[<span style="font-size: 2em">💡</span>]
|
|
:warning-caption: pass:[<span style="font-size: 2em">⚠</span>]
|
|
:toc:
|
|
:toclevels: 6
|
|
|
|
Ive been messing around with embedded rust recently, using the BBC micro:bit as a learning platform.
|
|
Its really cool to see a high level language achieving the same results as low level c.
|
|
|
|
However, one of my favorite features of rust, the ease of unit testing, is a bit less straightforward to do in cross-compiled, no-std projects.
|
|
Obviously we cant run tests on our local machine that rely on hardware only found on the target board,
|
|
but most of a project is going to be logic independent of the hardware its running on.
|
|
What we really want to do is be able to unit test those independent blocks of logic on our local dev machine.
|
|
|
|
== The Root Problem
|
|
|
|
The root of the problem is that our entire project is setup to depend on our target architecture and its hardware features.
|
|
(you are using cargo embed, right?)
|
|
As long as there is no compiler separation between our logic and our hardware interaction, we cant compile only one for our local machine while leaving out the rest.
|
|
Fortunately, that realization leads us directly to...
|
|
|
|
== The Solution
|
|
|
|
In Rust, the minimum unit of compilation is the crate.
|
|
This means that if we want to separate our logic from our hardware interaction, we have to put them in separate crates.
|
|
Thankfully, Rust has a feature called https://doc.rust-lang.org/cargo/reference/workspaces.html[workspaces] dedicated to managing several crates in a single project/repo.
|
|
|
|
So, what we will do is make a https://doc.rust-lang.org/cargo/reference/workspaces.html[virtual workspace] at the top level of our repo,
|
|
containing 2 or more crates: one (or more, if it makes sense) for our main hardware layer that is set up for cross compilation and flashing using cargo-embed,
|
|
one `#![no-std]` crate containing only hardware independent logic that can be used on any architecture, and do not have cross-compilation explicitly setup.
|
|
The latter set of crate(s) are the ones that we will be able to put unit tests in.
|
|
|
|
== Implementation
|
|
|
|
Our `main_hardware` crate will depend on the `independent_logic` crate, and our `independent_logic` crate cannot depend on any crate that is hardware specific, such as any HALs or BSPs in use.
|
|
|
|
Lets say that we have a project that looks something like this:
|
|
|
|
{{<highlight console "linenos=false">}}
|
|
.
|
|
├── .cargo
|
|
│ └── config
|
|
├── .gitignore
|
|
├── Cargo.toml
|
|
├── Embed.toml
|
|
├── LICENCE
|
|
├── README.md
|
|
├── build.rs
|
|
├── memory.x
|
|
└── src
|
|
├── calibration.rs
|
|
├── heading_drawing.rs
|
|
├── led.rs
|
|
├── line_drawing.rs
|
|
├── main.rs
|
|
└── tilt_compensation.rs
|
|
{{</highlight>}}
|
|
|
|
=== Separating the crates
|
|
|
|
`calibration.rs` and `main.rs` are the only modules that depend on hardware features, so they will be the modules going into `hardware_main`.
|
|
The rest will be going into `independent_logic`.
|
|
|
|
First we create the two new crates, with `hardware_main` being a binary crate and `independent_logic` being a library one, and we move the files to their respective crate.
|
|
|
|
Then, we move the existing `Cargo.toml`, `Embed.toml`, `build.rs`, `memory.x`, and `.cargo/config` into the `hardware_main`.
|
|
Then, we create a new `Cargo.toml` at the top level, with the only section being a `[workspace]` section,
|
|
including both of the crates in the workspace.
|
|
We edit the `Cargo.toml` of `hardware_main` to point to `independent_logic` as a https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-path-dependencies[path dependency], and remove any dependencies that are no longer used.
|
|
We edit the `Cargo.toml` of `independent_logic` to add any packages that our code depends on.
|
|
We edit `lib.rs` to declare all the modules in `independent_logic` (and declare the crate as `#![no_std]`),
|
|
and remove those declarations from `main.rs`.
|
|
Finally, in the `hardware_main` crate, we start running `cargo check` and fix all the imports that went from being `crate::` imports to `independent_logic::` imports.
|
|
|
|
In the end, our file tree should look something like this:
|
|
|
|
{{<highlight console "linenos=false">}}
|
|
.
|
|
├── .gitignore
|
|
├── Cargo.toml
|
|
├── LICENCE
|
|
├── README.md
|
|
├── hardware_main
|
|
│ ├── .cargo
|
|
│ │ └── config
|
|
│ ├── Cargo.toml
|
|
│ ├── Embed.toml
|
|
│ ├── build.rs
|
|
│ ├── memory.x
|
|
│ └── src
|
|
│ ├── calibration.rs
|
|
│ ├── led.rs
|
|
│ └── main.rs
|
|
└── independent_logic
|
|
├── Cargo.toml
|
|
└── src
|
|
├── heading_drawing.rs
|
|
├── lib.rs
|
|
├── line_drawing.rs
|
|
└── tilt_compensation.rs
|
|
{{</highlight>}}
|
|
|
|
=== Adding tests
|
|
|
|
Now that we have separated the crates from each other, we are free to add unit tests to `independent_logic` the same way we would for any 'normal' rust project.
|
|
However, we must keep in mind that we will only be able to run `cargo test` from inside the `independent_logic` crate.
|
|
Likewise, we will not be able to run `cargo build/check/embed` from the top level workspace, but must run it from the `hardware_main` crate, as that crate is bound to a specific target.
|
|
Cargo commands will generally also not work in the root workspace, as it will try to compile `hardware_main` for our local architecture, inevitably failing.
|