--- title: Toolchain Setup sidebar_label: Toolchain Setup --- import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; export const OsTabs = (props) => ( {/* eslint-disable-next-line */} {props.children} ); 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.) 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) 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 ``` ::: 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 ``` ::: 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 ``` ::: #### 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- ``` ## 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 ```sh cd zmk ``` ```sh cd zmk ``` ```sh cd zmk ``` 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. 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. ::: ### 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). :::