Jacob/zmk
1
0
Fork 0
forked from kofal.net/zmk
Code Pull Requests Activity

refactor(docs): Refactor the development section (#2438)

Browse Source
This commit is contained in:
Nicolas Munnich
2024-09-02 06:54:19 +02:00
committed by GitHub
parent aae4feeda8
commit 266227b580
33 changed files with 117 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
docs/docs/development/local-toolchain/build-flash.mdx Normal file
View File

@@ -0,0 +1,167 @@
---
title: Building and Flashing
sidebar_label: Building and Flashing
---
## Building
From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout:
```sh
cd app
```
To build for your particular keyboard, the behavior varies slightly depending on if you are building for a keyboard with
an onboard MCU, or one that uses an MCU board addon.
### Keyboard (Shield) + MCU Board
ZMK treats keyboards that take an MCU addon board as [shields](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html)
Given the following:
- MCU Board: Proton-C
- Keyboard PCB: kyria_left
- Keymap: default
You can build ZMK with the following:
```sh
west build -b proton_c -- -DSHIELD=kyria_left
```
### Keyboard With Onboard MCU
Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html) as far as Zephyr™ is concerned.
Given the following:
- Keyboard: Planck (rev6)
- Keymap: default
you can build ZMK with the following:
```sh
west build -b planck_rev6
```
### Pristine Building
When building for a new board and/or shield after having built one previously, you may need to enable the pristine build option. This option removes all existing files in the build directory before regenerating them, and can be enabled by adding either --pristine or -p to the command:
```sh
west build -p -b nice_nano_v2 -- -DSHIELD=kyria_left
```
### Building For Split Keyboards
:::note
For split keyboards, you will have to build and flash each side separately the first time you install ZMK.
:::
By default, the `build` command outputs a single .uf2 file named `zmk.uf2` so building left and then right immediately after will overwrite your left firmware. In addition, you will need to pristine build each side to ensure the correct files are used. To avoid having to pristine build every time and separate the left and right build files, we recommend setting up separate build directories for each half. You can do this by using the `-d` parameter and first building left into `build/left`:
```sh
west build -d build/left -b nice_nano_v2 -- -DSHIELD=kyria_left
```
and then building right into `build/right`:
```sh
west build -d build/right -b nice_nano_v2 -- -DSHIELD=kyria_right
```
This produces `left` and `right` subfolders under the `build` directory and two separate .uf2 files. For future work on a specific half, use the `-d` parameter again to ensure you are building into the correct location.
:::tip
Build times can be significantly reduced after the initial build by omitting all build arguments except the build directory, e.g. `west build -d build/left`. The additional options and intermediate build outputs from your initial build are cached and reused for unchanged files.
:::
### Building With External Modules
ZMK supports loading additional boards, shields, code, etc. from [external Zephyr modules](https://docs.zephyrproject.org/3.5.0/develop/modules.html), facilitating out-of-tree management and versioning independent of the ZMK repository. To build with any additional modules, use the `ZMK_EXTRA_MODULES` define added to your `west build` command.
For instance, building with the `my-vendor-keebs-module` checked out to your documents directory, you would build like:
```
west build -b nice_nano_v2 -- -DSHIELD=vendor_shield -DZMK_EXTRA_MODULES="C:/Users/myUser/Documents/my-vendor-keebs-module"
```
When adding multiple modules, make sure they are separated by a semicolon, e.g.:
```
west build -b nice_nano_v2 -- -DSHIELD=vendor_shield -DZMK_EXTRA_MODULES="C:/Users/myUser/Documents/my-vendor-keebs-module;C:/Users/myUser/Documents/my-other-keebs-module"
```
### Building from `zmk-config` Folder
Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](../../user-setup.mdx#github-repo) by adding
`-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.**
For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this:
```sh
west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config"
```
:::warning
The above command must still be invoked from the `zmk/app` directory as noted above, rather than the config directory. Otherwise, you will encounter errors such as `ERROR: source directory "." does not contain a CMakeLists.txt; is this really what you want to build?`. Alternatively you can add the `-s /path/to/zmk/app` flag to your `west` command.
:::
:::warning
If your config is also a [module](../../features/modules.mdx), then you should also add the root (the folder in which the `zephyr` folder is found) of your `zmk-config` as an [external module to build with](#building-with-external-modules).
:::
In order to make your `zmk-config` folder available when building within the VSCode Remote Container, you need to create a docker volume named `zmk-config`
by binding it to the full path of your config directory. If you have run the VSCode Remote Container before, it is likely that docker has created this
volume automatically -- we need to delete the default volume before binding it to the correct path. Follow the following steps:
1. Stop the container by exiting VSCode. You can verify no container is running via the command `docker ps`.
1. Remove all the containers that are not running via the command `docker container prune`. We need to remove the ZMK container before we can delete the default `zmk-config` volume referenced by it. If you do not want to delete all the containers that are not running, you can find the id of the ZMK container and use `docker rm` to delete that one only.
1. Remove the default volume via the command `docker volume rm zmk-config`.
Then you can bind the `zmk-config` volume to the correct path pointing to your local [zmk-config](customization.md) folder:
```sh
docker volume create --driver local -o o=bind -o type=none -o \
device="/full/path/to/your/zmk-config/" zmk-config
```
Now start VSCode and rebuild the container after being prompted. You should be able to see your zmk-config mounted to `/workspaces/zmk-config` inside the container. So you can build your custom firmware with `-DZMK_CONFIG="/workspaces/zmk-config/config"`.
## Flashing
The above build commands generate a UF2 file in `build/zephyr` (or
`build/left|right/zephyr` if you followed the instructions for splits) and is by
default named `zmk.uf2`. If your board supports USB Flashing Format (UF2), copy
that file onto the root of the USB mass storage device for your board. The
controller should flash your built firmware, unmount the USB storage device and
automatically restart once flashing is complete.
Alternatively, if your board supports flashing and you're not developing from
within a Dockerized environment, enable Device Firmware Upgrade (DFU) mode on
your board and run the following command to flash:
```sh
west flash
```
## Multi-CPU and Dual-Chip Bluetooth Boards
Zephyr supports running the Bluetooth host and controller on separate processors. In such a configuration, ZMK always runs on the host processor, but you may need to build and flash separate firmware for the controller. Zephyr provides sample code which can be used as the controller firmware for Bluetooth HCI over [RPMsg](https://docs.zephyrproject.org/3.5.0/samples/bluetooth/hci_rpmsg/README.html), [SPI](https://docs.zephyrproject.org/3.5.0/samples/bluetooth/hci_spi/README.html), [UART](https://docs.zephyrproject.org/3.5.0/samples/bluetooth/hci_uart/README.html), and [USB](https://docs.zephyrproject.org/3.5.0/samples/bluetooth/hci_usb/README.html). See [Zephyr's Bluetooth Stack Architecture documentation](https://docs.zephyrproject.org/3.5.0/connectivity/bluetooth/bluetooth-arch.html) for more details.
The following documentation shows how to build and flash ZMK for boards that use a dual-chip configuration.
### nRF5340
To build and flash the firmware for the nRF5340 development kit's network core, run the following command from the root of the ZMK repo:
```sh
cd zephyr/samples/bluetooth/hci_rpmsg
west build -b nrf5340dk_nrf5340_cpunet
west flash
```
You can then build and flash ZMK firmware using the normal steps described above. The network core's firmware only needs to be updated whenever ZMK upgrades to a new version of Zephyr.
For a custom nRF5340-based board, you will need to define two Zephyr boards: one for the application core and one for the network core. The [nRF5340 DK's board definition](https://github.com/zephyrproject-rtos/zephyr/tree/main/boards/arm/nrf5340dk_nrf5340) can be used as reference. Replace `nrf5340dk_nrf5340_cpunet` with the name of your network core board.

98
docs/docs/development/local-toolchain/ide-integration.mdx Normal file
View File

@@ -0,0 +1,98 @@
---
title: IDE Integration
sidebar_label: IDE Integration
---
## Visual Studio Code
Visual Studio Code needs to know some things about the project such as include
paths and compiler paths before features such as code completion, go to definition,
and graying out disabled code blocks will work. Fortunately, CMake can generate
that configuration for us automatically.
### Create a Compilation Database
To configure `west` to tell CMake to generate a compilation database, open a
terminal to the ZMK repository and run the following command:
```sh
west config build.cmake-args -- -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
```
Every [build](build-flash.mdx#building) will now update the database. You will
need to build once to create the database before code completion will work.
We'll tell Visual Studio Code where to find the database in the next step.
:::note
If you have set any other CMake arguments such as the path to your zmk-config, the
above command will overwrite them. You should instead provide the flag to export
compile commands and all other arguments surrounded by quotes. For example:
```sh
west config build.cmake-args -- "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DZMK_CONFIG=/path/to/zmk-config/config"
```
:::
### Create a C/C++ Configuration
Install the [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools),
then run **F1 > C/C++: Edit Configurations (UI)**. It should automatically create
a new configuration for you, but if the text box under **Configuration name** is empty,
click **Add Configuration**, enter a name, and click **OK**.
Change these options:
| Option | Value |
| ------------------------------------- | ------------------------------------------------------ |
| Compiler path | Path to your toolchain's GCC binary (see below) |
| IntelliSense mode | `linux-gcc-arm`, `windows-gcc-arm`, or `macos-gcc-arm` |
| Advanced Settings > Compiler commands | `${workspaceFolder}/app/build/compile_commands.json` |
If you are developing inside a Docker container, set the IntelliSense mode to `linux-gcc-arm` regardless of the host operating system.
#### Compiler path
Open VS Code's integrated terminal and run the following command:
```sh
cmake -P zephyr/cmake/verify-toolchain.cmake
```
This should print something like
```
-- ZEPHYR_TOOLCHAIN_VARIANT: zephyr
-- SDK_VERSION: 0.15.2
-- ZEPHYR_SDK_INSTALL_DIR : /home/marvin/.local/zephyr-sdk-0.15.2
```
Your compiler path is the value of `ZEPHYR_SDK_INSTALL_DIR` plus `/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc`, for example:
```
/home/marvin/.local/zephyr-sdk-0.15.2/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
```
If you are building for an platform other than ARM, replace `/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc` with the path to the compiler for the appropriate architecture, for example:
```
/home/marvin/.local/zephyr-sdk-0.15.2/riscv64-zephyr-elf/bin/riscv64-zephyr-elf-gcc
```
#### Compiler commands path
When building with all default options, the path to the compilation database file
is `${workspaceFolder}/app/build/compile_commands.json` as shown in the table above,
however some arguments to `west build` can change this path.
The `-d` or `--build-dir` option lets you change the build directory to something
other than `build`. Replace `build` in the above path with what you set this to.
For example, if you build with `-d build/my_shield`, the path is
`${workspaceFolder}/app/build/my_shield/compile_commands.json`. If you use this
to keep builds for multiple keyboards separate, you may want to create a separate
C/C++ configuration for each one in VS Code.
You can also build from the root folder of the project instead of the `app`
folder by adding `-S app` to your CMake arguments. In this case, simply remove
`app` from the path to `compile_commands.json`, for example,
`${workspaceFolder}/build/compile_commands.json`.

38
docs/docs/development/local-toolchain/posix-board.md Normal file
View File

@@ -0,0 +1,38 @@
---
title: Native Posix board target
---
In order to iterate quickly on firmware features, it can
be helpful to build and run the firmware on your local
workstation, with generated virtual press/release events
flowing into the handler functions.
## Prerequisites
In order to build targeting the `native_posix` board, you need to setup your system
with a compiler that can target 32-bit POSIX.
On Debian, you can do this with:
```sh
apt install -y gcc-multilib
```
## Building
To do this, you can build ZMK targeting the
`native_posix_64` board.
```sh
west build --pristine --board native_posix_64 -- -DZMK_CONFIG=tests/none/normal/
```
Once built, you can run the firmware locally:
```
./build/zephyr/zmk.exe
```
## Virtual Key Events
The virtual key presses are hardcoded in `boards/native_posix_64.overlay` file, should you want to change the sequence to test various actions like Mod-Tap, etc.

37
docs/docs/development/local-toolchain/pre-commit.md Normal file
View File

@@ -0,0 +1,37 @@
---
title: Pre-commit
---
ZMK uses [pre-commit](https://pre-commit.com/) to check for common errors and make sure the codebase is formatted consistently.
Pre-commit is run on every pull request. You can also install it locally to get the same checks run on every commit you make _before_ you submit a pull request.
## Installing pre-commit
Open a terminal and run:
```bash
pip3 install pre-commit
```
If this doesn't work, make sure [Python](https://www.python.org/) is installed and try again.
## Enabling Commit Hooks
Now that pre-commit is installed on your PC, you need to install it into the ZMK repo to enable it. Open a terminal to the ZMK repo directory and run:
```bash
pre-commit install
```
This should print a message such as
```
pre-commit installed at .git\hooks\pre-commit
```
Pre-commit will now automatically check your changes whenever you run `git commit`. If it detects a problem, it will describe the problem and cancel the commit. For simple problems such as incorrect formatting, it will also automatically fix the files so you can just `git add` them and try again.
## Automatically Enabling pre-commit
Pre-commit can be configured to automatically install itself into any newly cloned repository, so you don't have to remember to run `pre-commit install`. See the [pre-commit documentation](https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories) for instructions.

53
docs/docs/development/local-toolchain/setup/docker.md Normal file
View File

@@ -0,0 +1,53 @@
---
title: Docker
sidebar_label: Docker
---
:::note
Currently the Docker approach is only documented for [VS Code](https://github.com/microsoft/vscode) (not [Code OSS](https://github.com/microsoft/vscode/wiki/Differences-between-the-repository-and-Visual-Studio-Code)). While it can be replicated using [devcontainers](https://containers.dev/) this is not documented yet - contributions are welcome!
:::
### Source Code
First, you'll need to clone the ZMK source repository if you haven't already. Open a terminal and navigate to the folder you would like to place your `zmk` directory in, then run the following command:
```sh
git clone https://github.com/zmkfirmware/zmk.git
```
### Installing Development Tools
1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system.
2. Install [VS Code](https://code.visualstudio.com/).
3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
### Initialize & Update Zephyr Workspace
Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up:
![VS Code Dev Container Configuration Alert](../../../assets/dev-setup/vscode_devcontainer.png)
Click `Reopen in Container` in order to reopen the VS Code with the running container. If the alert fails to pop up or you accidentally close it, you can perform the same action by pressing `ctrl+shift+p` and selecting `Remote: Show Remote Menu`.
The first time you do this on your machine, it will pull the docker image down from the registry and build the container. Subsequent launches are much faster!
:::caution
The following step and any future [build commands](../build-flash.mdx) must be executed from the VS Code terminal _inside_ the container.
:::
Initialize the application and update to fetch modules, including Zephyr:
```sh
west init -l app/
west update
```
:::tip
This step pulls down quite a bit of tooling, be patient!
:::
:::info
You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code.
Your setup is complete once your container has restarted.
:::

20
docs/docs/development/local-toolchain/setup/index.md Normal file
View File

@@ -0,0 +1,20 @@
---
title: Getting Started
sidebar_label: Getting Started
---
:::tip
We recommend reading through the setup process before following it step by step, to ensure that you are happy with installing the required dependencies.
:::
## Environment Setup
There are two ways to set up the ZMK development environment:
- [Docker](docker.md): \
A self-contained development environment. It uses the same [Docker image which is used by the GitHub action](https://github.com/zmkfirmware/zmk-docker) for local development. Beyond the benefits of [dev/prod parity](https://12factor.net/dev-prod-parity), this approach may be easier to set up for some operating systems. No toolchain or dependencies are necessary when using Docker; the container image has the toolchain installed and set up to use.
- [Native](native.mdx):\
This uses your operating system directly. Usually runs slightly faster than the Docker approach, and can be preferable for users who already have the dependencies on their system.
Please see the [Docker](docker.md) instructions or [native](native.mdx) instructions to continue setup.

353
docs/docs/development/local-toolchain/setup/native.mdx Normal file
View File

@@ -0,0 +1,353 @@
---
title: Native Setup
sidebar_label: Native
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
export const OsTabs = (props) => (
<Tabs
groupId="operating-system"
defaultValue="ubuntu"
values={[
{ label: "Ubuntu", value: "ubuntu" },
{ label: "Windows", value: "win" },
{ label: "Mac OS", value: "mac" }
]}
>
{/* eslint-disable-next-line */}
{props.children}
</Tabs>
);
export const OsNoteTabs = (props) => (
<Tabs
groupId="operating-system"
defaultValue="win"
values={[
{ label: "Windows", value: "win" },
{ label: "Raspberry OS", value: "raspberryos" },
]}
>
{/* eslint-disable-next-line */}
{props.children}
</Tabs>
);
export const EnvTabs = (props) => (
<Tabs
groupId="python-environment"
defaultValue="venv"
values={[
{ label: "Install within Virtual Environment", value: "venv" },
{ label: "Install globally", value: "glob" },
]}
>
{/* eslint-disable-next-line */}
{props.children}
</Tabs>
);
export const WinTermTabs = (props) => (
<Tabs
groupId="windows-terminal-choice"
defaultValue="cmd"
values={[
{ label: "Command Prompt", value: "cmd" },
{ label: "Powershell", value: "ps" },
]}
>
{/* eslint-disable-next-line */}
{props.children}
</Tabs>
);
## 1. Install Zephyr Dependencies
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
:::info
Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) page may be of use for users of Linux distributions which are not based on Ubuntu.
:::
## 2. Source Code
Next, you'll need to clone the ZMK source repository if you haven't already. Open a terminal and navigate to the folder you would like to place your `zmk` directory in, then run the following command:
```sh
git clone https://github.com/zmkfirmware/zmk.git
```
Then step into the repository.
```sh
cd zmk
```
## 3. Get Zephyr and install Python dependencies
:::note
These steps are very similar to Zephyr's [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies) instructions, but specialized for ZMK.
:::
<EnvTabs>
<TabItem value="venv">
<Tabs groupId="operating-systems" defaultValue="ubuntu">
<TabItem value="ubuntu" label="Ubuntu">
1. Use `apt` to install Python `venv` package:
```sh
sudo apt install python3-venv
```
2. Create a new virtual environment and activate it:
```sh
python3 -m venv .venv
source .venv/bin/activate
```
</TabItem>
<TabItem value="win" label="Windows">
1. Create a new virtual environment:
```sh
python -m venv .venv
```
2. Activate the virtual environment:
<WinTermTabs>
<TabItem value="cmd">
```sh
.venv\Scripts\activate.bat
```
</TabItem>
<TabItem value="ps">
```powershell
.venv\Scripts\Activate.ps1
```
</TabItem>
</WinTermTabs>
</TabItem>
<TabItem value="mac" label="Mac OS">
1. Create a new virtual environment:
```sh
python3 -m venv .venv
```
2. Activate the virtual environment:
```sh
source .venv/bin/activate
```
</TabItem>
</Tabs>
Once activated your shell will be prefixed with `(.venv)`. The virtual environment can be deactivated at any time by running `deactivate`.
:::note
Remember to activate the virtual environment every time you start working.
:::
4. Install west:
```sh
pip install west
```
5. Initialize the application and update to fetch modules, including Zephyr:
```sh
west init -l app/
west update
```
:::tip
This step pulls down quite a bit of tooling, be patient!
:::
6. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
```
7. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip install -r zephyr/scripts/requirements-base.txt
```
</TabItem>
<TabItem value="glob">
<Tabs groupId="operating-systems" defaultValue="ubuntu">
<TabItem value="ubuntu" label="Ubuntu">
1. Install `west`:
```sh
pip3 install --user -U west
```
:::note
You need `~/.local/bin` to be on your `PATH` environment variable; verify that it is by running
```sh
west --version
```
If this prints an error rather than a `west` version number, then add `~/.local/bin` to your `PATH`:
```sh
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
```
:::
</TabItem>
<TabItem value="win" label="Windows">
1. Install `west`:
```sh
pip install -U west
```
:::note
You need the Python scripts directory to be on your PATH environment variable; verify that it is by running
```sh
west --version
```
If this prints an error rather than a `west` version number, then add said directory to your `PATH` with PowerShell:
```powershell
$Scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
$Path = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$Path;$Scripts", 'User')
$env:PATH += ";$Scripts"
```
:::
</TabItem>
<TabItem value="mac" label="Mac OS">
1. Install `west`:
```sh
pip3 install -U west
```
</TabItem>
</Tabs>
2. Initialize the application and update to fetch modules, including Zephyr:
```sh
west init -l app/
west update
```
:::tip
This step pulls down quite a bit of tooling, be patient!
:::
3. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
```sh
west zephyr-export
```
<Tabs groupId="operating-systems" defaultValue="ubuntu" className="secrettabs">
<TabItem value="ubuntu" label="Ubuntu">
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip3 install --user -r zephyr/scripts/requirements-base.txt
```
</TabItem>
<TabItem value="win" label="Windows">
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip install -r zephyr/scripts/requirements-base.txt
```
</TabItem>
<TabItem value="mac" label="Mac OS">
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`.
```sh
pip3 install -r zephyr/scripts/requirements-base.txt
```
</TabItem>
</Tabs>
</TabItem>
</EnvTabs>
## 4. Install Zephyr SDK
Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk).
### OS-Specific Notes
<OsNoteTabs>
<TabItem value="win">
`dfu-util` is required to flash devices that use DFU, but there is currently
no maintained package for it on Chocolatey. [QMK
Toolbox](https://github.com/qmk/qmk_toolbox) contains a working version of it
though.
</TabItem>
<TabItem value="raspberryos">
#### Install cross-compile toolchain
Because Raspberry OS runs on the same architecture (but different ABI) as ARM keyboard MCUs, the operating system's installed [cross compilers](https://docs.zephyrproject.org/3.5.0/develop/toolchains/other_x_compilers.html) can be used to target the different ABI. Building for non-ARM MCUs has not been tested.
First, the cross compiler should be installed:
```sh
sudo apt install gcc-arm-none-eabi
```
Next, we'll configure Zephyr with some [environment variables](https://docs.zephyrproject.org/3.5.0/develop/env_vars.html#env-vars) needed to find the cross compiler. Create a file named `~/.zephyrrc` if it doesn't exist, and add these lines to it:
```sh
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
export CROSS_COMPILE=/usr/bin/arm-none-eabi-
```
</TabItem>
</OsNoteTabs>
Your setup is now complete.

22
docs/docs/development/local-toolchain/tests.md Normal file
View File

@@ -0,0 +1,22 @@
---
title: Tests
sidebar_label: Tests
---
- Running tests requires [native posix support](posix-board.md).
- Any folder under `/app/tests` containing `native_posix_64.keymap` will be selected when running `west test`.
- Run tests from within the `/zmk/app` directory.
- Run a single test with `west test <testname>`, like `west test tests/toggle-layer/normal`.
## Creating a New Test Set
1. Copy the test set that most closely resembles the tests you will be creating.
2. Rename the newly created test set to the behavior you're testing e.g, toggle-layer
3. Modify `behavior_keymap.dtsi` to create a keymap using the behavior and related behaviors
4. Modify `test_case/native_posix_64.keymap` for a simulated use case
5. Modify `test_case/events.patterns` to collect relevant logs to the test
- See: [sed manual](https://www.gnu.org/software/sed/manual/sed.html) and
[tutorial](https://www.digitalocean.com/community/tutorials/the-basics-of-using-the-sed-stream-editor-to-manipulate-text-in-linux)
6. Modify `test_case/keycode_events.snapshot` for to include the expected output
7. Rename the `test_case` folder to describe the test.
8. Repeat steps 4 to 7 for every test case