4 KiB
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:
- Install Docker or Podman (recommended) and, if using Podman, configure the docker
registry. On Debian or Ubuntu, you can do both by running:
sudo apt-get install podman echo 'unqualified-search-registries = ["docker.io"]' > $XDG_CONFIG_HOME/containers/registries.conf
- 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/podman, 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.
To switch between Docker and Podman, set the DOCKER_BIN
variable in the
script (defaults to podman
). If using Docker and the user is not in the
docker-group, then one can use Docker in sudo-mode by using the -s
flag for
the script. If using Podman, running in rootless mode is recommended.
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