zmk/scripts/readme.md

This folder contains scripts that automate installing and building using a local toolchain. The scripts provide an alternative to using Github Actions and the developer toolchain.

If the zmk-config repo contains a combos.dtsi file, the script will also automatically update the MAX_COMBOS_PER_KEY and MAX_KEYS_PER_COMBO settings for all boards, depending on the combos specified in combos.dtsi.

Build steps

1. Clone the ZMK repository

Clone the ZMK repository and checkout the branch that you want to build against. By default the build script will look for the ZMK repo in ~/zmk. Other locations can be specified with --host-zmk-dir or by changing the default location for HOST_ZMK_DIR inside the script.

For example, to build against my main-3.2 branch, run:

cd "$HOME"
git clone https://github.com/urob/zmk
git checkout main-3.2

2. Clone your zmk-config repository

By default the build script will look for the zmk-config repo in ~/zmk-config. Other locations can be specified with --host-config-dir or by changing the default location for HOST_CONFIG_DIR inside the script.

For example, to use my zmk-config repo, run:

cd "$HOME"
git clone https://github.com/urob/zmk-config

3. Install the build requisites

The build script can be used to install either a "docker" or a "local" toolchain. If unsure, I recommend using the docker toolchain. Depending on your installation choice, do one of the following:

1. Install the Docker engine following the instructions for your operating system. On Debian and Ubuntu, I recommend using the "Install from Docker's apt repository" option.
2. Install a local developer toolchain. The zmk_local_install.sh script in this repository automates the process for Debian-based operating system.

4. Run the build script

Run the zmk_build.sh script to build your boards. By default, the script will build all boards specified in build.yaml in your zmk-config repo. The default can be overwritten with the -b option.

If using docker, the script will pull down the required dependencies the first time it is used. The script will automatically detect whether the build requirement have changed, and will only re-download the dependencies if needed.

In order to easily switch between multiple ZMK branches that have different build requirements, one can specify the desired Zephyr version using the -v option. Docker container and volumes are index by the Zephyr version, so switching between Zephyr version won't require re-downloading new dependencies. In order to force re-installing all build requirements, pass the -c option, which will wipe out the Docker container and volume.

By default the script will copy the firmware into the OUTPUT_DIR folder specified in the script. Other locations can be specified using the --output-dir argument.

In order to start Docker in sudo-mode (required when the user is not in the docker-group), use -s.

One can pass custom options to west by preluding them with --.

For example, to build my boards using Zephyr version 3.2 in sudo mode and pass the "pristine" option to west, run:

zmk_build.sh -s -v 3.2 -- -p

See the script for a full set of options.

Developing interactively using Docker

The docker container can be entered interactively using with all the necessary mounts using: The script shares a build environment with the build script (again indexed by Zephyr versions).

For example, to start an interactive Docker session in sudo mode using Zephyr version 3.2, run:

zmk_run_docker.sh -s -v 3.2