229 lines
8.5 KiB
Text
229 lines
8.5 KiB
Text
---
|
|
title: Toolchain Setup
|
|
sidebar_label: Toolchain Setup
|
|
---
|
|
|
|
import Tabs from "@theme/Tabs";
|
|
import TabItem from "@theme/TabItem";
|
|
|
|
export const OsTabs = (props) => (
|
|
<Tabs
|
|
groupId="operating-systems"
|
|
defaultValue="linux"
|
|
values={[
|
|
{ label: "VS Code & Docker", value: "docker" },
|
|
{ label: "Linux", value: "linux" },
|
|
{ label: "Windows", value: "win" },
|
|
{ label: "macOS", value: "mac" },
|
|
{ label: "Raspberry OS", value: "raspberryos" },
|
|
]}
|
|
>
|
|
{/* eslint-disable-next-line */}
|
|
{props.children}
|
|
</Tabs>
|
|
);
|
|
|
|
This guide will show you how to set up a development environment for building ZMK locally.
|
|
|
|
## Install Zephyr and West
|
|
|
|
Click the operating system you are using. (The VS Code & Docker option can be used on any OS.)
|
|
|
|
<OsTabs>
|
|
<TabItem value="docker">
|
|
|
|
This option 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 you'll be using already has the toolchain installed and set up to use.
|
|
|
|
1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system.
|
|
2. Install [Visual Studio Code](https://code.visualstudio.com/)
|
|
3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
|
|
|
|
</TabItem>
|
|
<TabItem value="linux">
|
|
|
|
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:
|
|
|
|
1. [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
|
|
2. [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
|
|
3. [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies)
|
|
4. [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
|
|
|
|
Return to this guide once you are finished with all four sections.
|
|
|
|
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 distributions which are not based on Ubuntu.
|
|
|
|
:::info
|
|
ZMK does not need all of the additional dependencies found in Zephyr's `requirements.txt`, only those found in `requirements-base.txt`
|
|
|
|
```diff
|
|
- pip3 install -r zephyr/scripts/requirements.txt
|
|
+ pip3 install -r zephyr/scripts/requirements-base.txt
|
|
```
|
|
|
|
:::
|
|
|
|
</TabItem>
|
|
<TabItem value="win">
|
|
|
|
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:
|
|
|
|
1. [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
|
|
2. [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
|
|
3. [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies)
|
|
4. [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
|
|
|
|
Return to this guide once you are finished with all four sections.
|
|
|
|
`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.
|
|
|
|
:::info
|
|
ZMK does not need all of the additional dependencies found in Zephyr's `requirements.txt`, only those found in `requirements-base.txt`
|
|
|
|
```diff
|
|
- pip3 install -r zephyr/scripts/requirements.txt
|
|
+ pip3 install -r zephyr/scripts/requirements-base.txt
|
|
```
|
|
|
|
:::
|
|
|
|
</TabItem>
|
|
<TabItem value="mac">
|
|
|
|
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:
|
|
|
|
1. [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
|
|
2. [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
|
|
3. [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies)
|
|
4. [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
|
|
|
|
Return to this guide once you are finished with all four sections.
|
|
|
|
:::info
|
|
ZMK does not need all of the additional dependencies found in Zephyr's `requirements.txt`, only those found in `requirements-base.txt`
|
|
|
|
```diff
|
|
- pip3 install -r zephyr/scripts/requirements.txt
|
|
+ pip3 install -r zephyr/scripts/requirements-base.txt
|
|
```
|
|
|
|
:::
|
|
|
|
</TabItem>
|
|
<TabItem value="raspberryos">
|
|
|
|
#### Install Base Dependencies
|
|
|
|
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions for Ubuntu under these sections:
|
|
|
|
1. [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
|
|
2. [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
|
|
3. [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies)
|
|
4. [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk)
|
|
|
|
Return to this guide once you are finished with all four sections.
|
|
|
|
:::info
|
|
ZMK does not need all of the additional dependencies found in Zephyr's `requirements.txt`, only those found in `requirements-base.txt`
|
|
|
|
```diff
|
|
- pip3 install -r zephyr/scripts/requirements.txt
|
|
+ pip3 install -r zephyr/scripts/requirements-base.txt
|
|
```
|
|
|
|
:::
|
|
|
|
#### 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>
|
|
</OsTabs>
|
|
|
|
## Get Source Code
|
|
|
|
Next, you'll need to clone the ZMK source repository if you haven't already. Navigate to the folder you would like to place your `zmk` directory in and run the following command:
|
|
|
|
```
|
|
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
|
|
|
|
<OsTabs>
|
|
<TabItem value="linux">
|
|
|
|
```sh
|
|
cd zmk
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="mac">
|
|
|
|
```sh
|
|
cd zmk
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="win">
|
|
|
|
```sh
|
|
cd zmk
|
|
```
|
|
|
|
</TabItem>
|
|
|
|
<TabItem value="docker">
|
|
|
|
Open the `zmk` checkout folder in VS Code. The repository includes a configuration for containerized development, so an alert will pop up:
|
|
|
|
|
|
|
|
Click `Reopen in Container` in order to reopen the VS Code with the running container.
|
|
|
|
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!
|
|
|
|
:::warning
|
|
All subsequent steps must be performed from the VS Code terminal _inside_ the container.
|
|
:::
|
|
|
|
</TabItem>
|
|
</OsTabs>
|
|
|
|
### Initialize the Application
|
|
|
|
```sh
|
|
west init -l app/
|
|
```
|
|
|
|
### Update to Fetch Modules
|
|
|
|
```sh
|
|
west update
|
|
```
|
|
|
|
:::tip
|
|
This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!
|
|
:::
|
|
|
|
:::info
|
|
Once your container is restarted, proceed to [Building and Flashing](development/build-flash.mdx).
|
|
:::
|