Have run, test, flash, bench, and debug targets that work across host platforms

[rrbutani]

what

Targets:

• run -> flash and open a console
• flash -> just flash (lm4flash)
• bench -> flash + post-process serial output
  • using µbench
• debug -> usual gdb + openocd debug flow
• test -> ...
  • eventually we want to use defmt-test (requires probe-rs), for now we'll do something bespoke: like the solution for benchmarking (only support one off tests, have the xtask` look for a sigil, etc.)

This is a prerequisite to testing/benchmarking on the board in CI.

steps

• (Runner) The above is essentially describing a custom runner with the following modes:
  • flash (no arguments)
    • needs to:
      • find/grab lm4flash
      • find llvm-objcopy or similar
      • process the ELF
      • flash it
  • run (--debug as a potential arg)
    • needs to:
      • run flash
      • if --debug:
        • find gdb, find openocd, launch it with the right platform specific stuff
      • otherwise:
        • open picocom if available, otherwise run the built-in output only console viewer
  • bench (--capture as a potential arg)
    • this is just run but with special post-processing
  • test
    • this is also run but with special post-processing
• add aliases for the above to .cargo/config
• add the above as VSCode build tasks
• [ ]

where

branch: feat-dx

open questions

xtask crate

We have some options as to how we "add" these tasks to Cargo in a developer friendly way.

• the usual route is the xtask pattern: a separate crate in your repo's workspace that you effectively use as a runner by introducing aliases that prefix commands with run -p xtask --
  • unfortunately this isn't a great fit for embedded because we don't have a way to tell Cargo to build a particular crate for the host platform while also having our embedded device crates build for embedded (i.e. thumbv7em-none-eabihf) by default
    • forced-target would solve this problem but unfortunately it is not yet stable (Tracking Issue for per-package-target rust-lang/cargo#9406) and we'd rather not move to nightly Rust
    • the knurling-rs folks get around this by introducing nested workspaces, with the inner one targeting embedded (this definitely works but is a little involved; developers also need to be aware of which workspace they are currently in when running commands)
  • this also means developers need to learn a set of aliases and it opens the door for the main build depending on xtask specific flows which in turn means that cargo subcommands (i.e. cargo-asm, cargo-bloat, etc.) will no longer work

For our use case, I think introducing an xtask style crate in our workspace that we explicitly use as the cargo runner makes the most sense. This:

• keeps the potential scope of the crate limited
• lets us reuse existing cargo subcommands like build, run, test, and bench

The downside to this approach is that we cannot use a default build.target. After trying a bunch of other potential solutions (outer workspace with host tools like xtask + some glue to try to proxy subcommands (but not custom subcommands) into the main workspace, trying to explicitly set the target of the xtask crate in aliases, trying to otherwise hide the .cargo/config from the xtask crate, having the xtask crate be outside of the workspace, using unstable cargo features that let us specify config options in args, etc.) this seems like the least-worst option, mostly because:

• this lets subcommands work
• we can paper over the pain by shadowing the common Cargo aliases (b, r, t) to include the target triple (but we cannot shadow the subcommands)
• we can introduce a compile_error!() into the main crate that's gated on the target triple so that it's apparent to users that they just need to add a flag to fix the errors they're seeing
• once forced-target is stable, it'll be easy to switch over and we're not introducing any other complexity that we'd want to remove at that point (i.e. nested workspaces)

VSCode and what we will support

As described here, this xtask crate will be doing a fair bit of work to find/grab host tools. Would we want to update the VSCode configuration to lean on this somehow? Alternatively, do we want to take the stance that: we'll support running cargo ... with minimal effort on all the major platforms but for VSCode support you either have to use nix or you're on your own? (I'm leaning towards yes)