Recommended way to build out-of-tree boards or shields?

[jablko]

Is there documentation on how to build out-of-tree boards or shields?

I have three involved repositories, I think:

• https://github.com/zmkfirmware/zmk
• My zmk-config
• The out-of-tree shield

To build them, I added to my config/west.yml:

manifest:
  ...
  projects:
    - name: revxlp-config
      remote: petejohanson
      revision: HEAD

Then to my build.yaml I added:

include:
  - board: seeeduino_xiao_ble
    shield: revxlp
    cmake-args: -DBOARD_ROOT="${GITHUB_WORKSPACE}/revxlp-config/config"

It worked, but is this the recommended way/is there a better one? Is there documentation on how to build out-of-tree boards or shields, or on the BOARD_ROOT variable? Related: I found this completed issue on documenting the ZMK_CONFIG variable.

Before I got it working I tried adding to my config/west.yml:

manifest:
  ...
  projects:
    - name: revxlp
      remote: petejohanson
      repo-path: revxlp-config/config/boards/shields/revxlp
      revision: HEAD

That failed: fatal: repository 'https://github.com/petejohanson/revxlp-config/config/boards/shields/revxlp/' not found. West can't clone a repository's subdirectory?

In this case at least the out-of-tree repository is laid out just like the zmk repository (and my zmk-config repository, also), so the next thing I tried is cloning it over top of the zmk directory, by adding to my config/west.yml:

manifest:
  ...
  projects:
    - name: revxlp-config
      remote: petejohanson
      revision: HEAD
      path: zmk

That also failed: Hint: project revxlp-config path "zmk" is taken by project zmk. I didn't try cloning it over top of the root, zmk-config directory --- I doubt that's possible?

That's when I found the BOARD_ROOT and cmake-args variables --- is this the recommended way to build out-of-tree boards or shields?

[caksoylar]

Building with boards/shields found in Zephyr modules is now officially supported via #1989. The setup script now creates a Zephyr module with a boards folder by default (see the template repo), but existing repos like https://github.com/petejohanson/revxlp-config will need to be updated to have /zephyr/module.yml and /config/boards folder moved to /boards.

Here is the updated documentation on building with modules and the new shield guide that encourages defining new shields as modules.