I'm trying to set up and document a workflow for active development of a core, while still being able to build sketches with arduino-cli.

With 0.21 (as well as previous versions, I believe), I'm running into trouble figuring out a reasonable development workflow. Reading through the arduino-cli sketch build documentation, I don't see a way to do what I want or an explanation of what the expected behavior should be.

Because there's no way for arduino-cli to install the required tools for a platform from a core checked out into $(ARDUINO_DIRECTORIES_USER)/hardware, it's been necessary to "prime" the system by installing a prepackaged version of the core with arduino-cli core install $mycore. That will download a copy of the core and resolve compiler and tools dependencies.

After that, I git clone a copy of the HEAD of the core to $(ARDUINO_DIRECTORIES_USER)/hardware

At this point, if I try to use arduino-cli to build a sketch and supply a fqbn, it will use the prepackaged version of the core downloaded with the package manager.

Doc bug: I don't believe there is documentation about what the expected search order is for a core. (Library resolution on the other hand, is now documented incredibly well at https://arduino.github.io/arduino-cli/0.21/sketch-build-process/#dependency-resolution - Whoever wrote those docs has my gratitude. Historically figuring out that dependency resolution was a huge pain. The new docs are just fantastic. Thank you!)

Functionality issue: I believe that if a user has placed a local, unpackaged core in their hardware/ directory, it ought to be used in preference to one downloaded through the boards manager. That said, this would potentially be a breaking change.

I'd be very happy if there were some way to hint to arduino-cli that it should prefer a core in the hardware subdir of the user directory/sketchbook, either in the global config or on the command-line. Alternatively, I'd love it if there were a way to install tools/dependencies for a core checked out into hardware.

Or is there a more 'arduino-ish' way to do this?

Thanks!