zmk_mf68/docs/docs/dev-setup.md at 9e62cc7069fe5bf8e75128ea6d092160013aa9cb

5.1 KiB

Raw Blame History

id	title	sidebar_label
dev-setup	Basic Setup	Basic Setup

Prerequisites

A unix-like environment with the following base packages installed:

Git
Python 3
pip
wget
devicetree compiler
CMake
dfu-util
Various build essentials, e.g. gcc, automake, autoconf

Debian/Ubuntu

On Debian and Ubuntu, this can be accomplished with:

sudo apt update
sudo apt install -y \
    git \
    wget \
    autoconf \
	automake \
	build-essential \
	ccache \
	device-tree-compiler \
	dfu-util \
	g++ \
	gcc \
	gcc-multilib \
	libtool \
	make \
    ninja-build \
    cmake \
	python3-dev \
	python3-pip \
	python3-setuptools \
	xz-utils

Fedora

TODO

macOS

TODO

WSL

Windows Subsystem for Linux can use various Linux distributions. Find a WSL installation on the Windows Store.

After installing your preferred flavor, follow the directions above on Debian/Ubuntu or Fedora.

:::note On WSL2 don't put the project files into /mnt/c/ as file I/O speeds are extremely slow. Instead, run everything in the Linux system and use cp to move files over to /mnt/c/ as needed. :::

Setup

West Build Command

west is the Zephyr™ meta-tool used to configure and build Zephyr™ applications. It can be installed by using the pip python package manager:

pip3 install --user west

:::note If you don't already have it configured, you may need to update your PATH to include the pip install path. See User Installs and Stack Overflow for more details. :::

Zephyr™ ARM SDK

To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system:

export ZSDK_VERSION=0.11.2
wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \
	sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d /opt/toolchains/zephyr-sdk-${ZSDK_VERSION} && \
	rm "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run"

The installation will prompt with several questions about installation location, and creating a default ~/.zephyrrc for you with various variables. The defaults shouldn normally work as expected.

Source Code

Next, you'll need to clone the ZMK source repository if you haven't already:

git clone https://github.com/zmkfirmware/zmk.git

Initialize & Update Zephyr Workspace

Since ZMK is built as a Zephyr™ application, the next step is to use west to initialize and update your workspace. The ZMK Zephyr™ application is in the app/ source directory:

Step into the repository

cd zmk

Initialize West

west init -l app/

Update To Fetch Modules

west update

Export Zephyr™ Core

west zephyr-export

Install Zephyr Python Dependencies

pip3 install --user -r zephyr/scripts/requirements.txt

Environment Variables

By default, the Zephyr™ SDK will create a file named ~/.zephyrrc with the correct environment variables to build ZMK. We suggest two main options for how to load those settings.

Per Shell

To load the Zephyr environment properly for just one transient shell, run:

source zmk/zephyr/zephyr-env.sh

All Shells

To load the environment variables for your shell every time, append the existing ~/.zephyrrc file to your shell's RC file and then start a new shell.

Bash

cat ~/.zephyrrc >> ~/.bashrc

ZSH

cat ~/.zephyrrc >> ~/.zshrc

Build

Actually building the ZMK firmware occurs within the app/ subdirectory of the ZMK repository. To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with an onboard MCU, or one that uses a MCU board addon.

Keyboard (Shield) + MCU Board

ZMK treats keyboards that take a MCU addon board as shields, and treats the smaller MCU board as the true board

Given the following:

MCU Board: Proton-C
Keyboard PCB: kyria
Keymap: default

You can build ZMK with the following:

west build -b proton_c -- -DSHIELD=kyria -DKEYMAP=default

Keyboard With Onboard MCU

Keyboards with onboard MCU chips are simply treated as the board as far as Zephyr™ is concerned.