docs: update dev env setup guide
Renamed the "Basic Setup" page to "Toolchain Setup" to make it clearer that this is for setting up a development environment for local builds. Linked to the relevant Zephyr setup documentation instead of duplicating that information in our guide. This also switches Windows and macOS setup to using the Zephyr SDK, which is much easier to install. Updated the command for installing Zephyr's Python dependencies to be OS specific, as Windows and macOS don't need the --user flag. Updated the IDE integration page with instructions for determining the compiler path that work with the latest version of the Zephyr SDK.
This commit is contained in:
Joel Spadin
Pete Johanson
parent
a82a0ec496
commit
82ff6d8e85
7 changed files with 168 additions and 447 deletions
docs/docs
assets/env-var
development
Binary file not shown.
|
Before 
(image error) Size: 17 KiB |
Binary file not shown.
|
Before 
(image error) Size: 7.7 KiB |
Binary file not shown.
|
Before 
(image error) Size: 60 KiB |
Binary file not shown.
|
Before 
(image error) Size: 50 KiB |
Binary file not shown.
|
Before 
(image error) Size: 7.1 KiB |
|
|
@ -59,86 +59,41 @@ 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 | gcc-arm |
|
||||
| Advanced Settings > Compiler commands | `${workspaceFolder}/app/build/compile_commands.json` |
|
||||
| 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
|
||||
|
||||
<OsTabs>
|
||||
<TabItem value="debian">
|
||||
|
||||
Open VS Code's integrated terminal and run the following commands. It will print
|
||||
your compiler path.
|
||||
|
||||
```sh
|
||||
source zephyr/zephyr-env.sh
|
||||
echo ${ZEPHYR_SDK_INSTALL_DIR}/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
|
||||
```
|
||||
|
||||
:::note
|
||||
You will need to update this path any time you switch to a new version of the Zephyr SDK.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
Your compiler path is
|
||||
Open VS Code's integrated terminal and run the following command:
|
||||
|
||||
```
|
||||
${env:GNUARMEMB_TOOLCHAIN_PATH}/bin/arm-none-eabi-gcc.exe
|
||||
cmake -P zephyr/cmake/verify-toolchain.cmake
|
||||
```
|
||||
|
||||
This assumes `GNUARMEMB_TOOLCHAIN_PATH` is set in your system or user environment variables.
|
||||
If not, you will need to list the full path instead of using the `${env}` placeholder.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac">
|
||||
|
||||
Open VS Code's integrated terminal and run the following command. It will print
|
||||
your compiler path.
|
||||
|
||||
```sh
|
||||
echo ${GNUARMEMB_TOOLCHAIN_PATH}/bin/arm-none-eabi-gcc
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="raspberryos">
|
||||
|
||||
Your compiler path is
|
||||
This should print something like
|
||||
|
||||
```
|
||||
/usr/bin/arm-none-eabi-gcc
|
||||
-- ZEPHYR_TOOLCHAIN_VARIANT: zephyr
|
||||
-- SDK_VERSION: 0.15.2
|
||||
-- ZEPHYR_SDK_INSTALL_DIR : /home/marvin/.local/zephyr-sdk-0.15.2
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fedora">
|
||||
|
||||
Open VS Code's integrated terminal and run the following commands. It will print
|
||||
your compiler path.
|
||||
|
||||
```sh
|
||||
source zephyr/zephyr-env.sh
|
||||
echo ${ZEPHYR_SDK_INSTALL_DIR}/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
|
||||
```
|
||||
|
||||
:::note
|
||||
You will need to update this path any time you switch to a new version of the Zephyr SDK.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="docker">
|
||||
|
||||
Your compiler path is
|
||||
Your compiler path is the value of `ZEPHYR_SDK_INSTALL_DIR` plus `/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc`, for example:
|
||||
|
||||
```
|
||||
${env:ZEPHYR_SDK_INSTALL_DIR}/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
|
||||
/home/marvin/.local/zephyr-sdk-0.15.2/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: Basic Setup
|
||||
sidebar_label: Basic Setup
|
||||
title: Toolchain Setup
|
||||
sidebar_label: Toolchain Setup
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
|
|
@ -10,287 +10,84 @@ export const OsTabs = (props) => (<Tabs
|
|||
groupId="operating-systems"
|
||||
defaultValue="debian"
|
||||
values={[
|
||||
{label: 'VS Code & Docker', value: 'docker'},
|
||||
{label: 'Debian/Ubuntu', value: 'debian'},
|
||||
{label: 'Windows', value: 'win'},
|
||||
{label: 'macOS', value: 'mac'},
|
||||
{label: 'Raspberry OS', value: 'raspberryos'},
|
||||
{label: 'Fedora', value: 'fedora'},
|
||||
{label: 'VS Code & Docker', value: 'docker'},
|
||||
]
|
||||
}>{props.children}</Tabs>);
|
||||
|
||||
## Prerequisites
|
||||
This guide will show you how to set up a development environment for building ZMK locally.
|
||||
|
||||
ZMK requires the following base packages to first be installed:
|
||||
## Install Dependencies
|
||||
|
||||
- Git
|
||||
- Python 3
|
||||
- `pip`
|
||||
- `wget`
|
||||
- devicetree compiler
|
||||
- CMake
|
||||
- `dfu-util`
|
||||
- Various build essentials, e.g. gcc, automake, autoconf
|
||||
Click the operating system you are using. (The VS Code & Docker option can be used on any OS.)
|
||||
|
||||
<OsTabs>
|
||||
<TabItem value="docker">
|
||||
|
||||
This option use 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 is also the easiest to set up. 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)
|
||||
|
||||
:::info
|
||||
The docker container already includes `west`. Skip past the following section to [Get Source Code](#get-source-code).
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="debian">
|
||||
|
||||
On Debian and Ubuntu, we'll use `apt` to install our base dependencies:
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html) and follow the instructions under these sections:
|
||||
|
||||
First, if you haven't updated recently, or if this is a new install,
|
||||
you should update to get the latest package information:
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-dependencies)
|
||||
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-zephyr-sdk)
|
||||
|
||||
```sh
|
||||
sudo apt update
|
||||
```
|
||||
|
||||
With the latest package information, you can now install the base dependencies:
|
||||
|
||||
```sh
|
||||
sudo apt install -y \
|
||||
git \
|
||||
wget \
|
||||
autoconf \
|
||||
automake \
|
||||
build-essential \
|
||||
bzip2 \
|
||||
ccache \
|
||||
device-tree-compiler \
|
||||
dfu-util \
|
||||
g++ \
|
||||
gcc \
|
||||
libtool \
|
||||
make \
|
||||
ninja-build \
|
||||
cmake \
|
||||
python3-dev \
|
||||
python3-pip \
|
||||
python3-setuptools \
|
||||
xz-utils
|
||||
```
|
||||
|
||||
:::note
|
||||
Recent LTS releases of Debian and Ubuntu may include outdated CMake versions. If the output of `cmake --version` is older than 3.20, upgrade your distribution (e.g., from Ubuntu 20.04 LTS to Ubuntu 22.04 LTS), or else install CMake version 3.20 or newer manually (e.g, from Debian backports or from PyPI with `pip install --user cmake`).
|
||||
:::
|
||||
</TabItem>
|
||||
<TabItem value="raspberryos">
|
||||
|
||||
On Raspberry OS, we'll use `apt` to install our base dependencies:
|
||||
|
||||
First, if you haven't updated recently, or if this is a new install,
|
||||
you should update to get the latest package information:
|
||||
|
||||
```sh
|
||||
sudo apt update
|
||||
```
|
||||
|
||||
With the latest package information, you can now install the base dependencies:
|
||||
|
||||
```sh
|
||||
sudo apt install -y \
|
||||
git \
|
||||
wget \
|
||||
autoconf \
|
||||
automake \
|
||||
build-essential \
|
||||
bzip2 \
|
||||
ccache \
|
||||
device-tree-compiler \
|
||||
dfu-util \
|
||||
g++ \
|
||||
gcc \
|
||||
libtool \
|
||||
make \
|
||||
ninja-build \
|
||||
cmake \
|
||||
python3-dev \
|
||||
python3-pip \
|
||||
python3-setuptools \
|
||||
xz-utils
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fedora">
|
||||
|
||||
On Fedora, we'll use `dnf` to install our base dependencies:
|
||||
|
||||
#### DNF Update
|
||||
|
||||
First, if you haven't updated recently, or if this is a new install,
|
||||
you should update to get the latest package information:
|
||||
|
||||
```sh
|
||||
sudo dnf update
|
||||
```
|
||||
|
||||
#### Install Dependencies
|
||||
|
||||
With the latest package information, you can now install the base dependencies:
|
||||
|
||||
```sh
|
||||
sudo dnf install -y \
|
||||
git \
|
||||
wget \
|
||||
autoconf \
|
||||
automake \
|
||||
bzip2 \
|
||||
ccache \
|
||||
dtc \
|
||||
dfu-util \
|
||||
g++ \
|
||||
gcc \
|
||||
libtool \
|
||||
make \
|
||||
ninja-build \
|
||||
cmake \
|
||||
python3-devel \
|
||||
python3-pip \
|
||||
python3-setuptools \
|
||||
xz
|
||||
```
|
||||
Return to this guide once you are finished with each section.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
:::note
|
||||
Use `cmd.exe` with these instructions rather than PowerShell.
|
||||
:::
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html) and follow the instructions under these sections:
|
||||
|
||||
Chocolatey is recommended and used for the following instructions. You can manually install each of these applications and add them to your `PATH` if you don't want to use Chocolatey.
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-dependencies)
|
||||
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-zephyr-sdk)
|
||||
|
||||
1. [Install Chocolatey](https://chocolatey.org/install)
|
||||
2. Open `cmd.exe` as **Administrator**
|
||||
3. Run the following `choco` commands:
|
||||
```shell
|
||||
choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
|
||||
choco install ninja gperf python git
|
||||
```
|
||||
Return to this guide once you are finished with each section.
|
||||
|
||||
It is recommended to install `dfu-util` to avoid any later confusion while flashing devices. You can do this by running this command with chocolatey:
|
||||
|
||||
```shell
|
||||
choco install dfu-util
|
||||
```
|
||||
`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="mac">
|
||||
|
||||
#### Homebrew
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html) and follow the instructions under these sections:
|
||||
|
||||
Homebrew is required to install the system dependencies. If you haven't done so, visit [Homebrew](https://brew.sh/) for instructions. Once installed, use it to install the base dependencies:
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-dependencies)
|
||||
- [Install Zephyr SDK](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-zephyr-sdk)
|
||||
|
||||
```
|
||||
brew install cmake ninja python3 ccache dtc git wget dfu-util
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="docker">
|
||||
|
||||
This setup leverages the same [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 is also the easiest to set up. 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 [VS Code](https://code.visualstudio.com/)
|
||||
3. Install the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
|
||||
|
||||
:::info
|
||||
The docker container includes `west` and the compilation toolchain. If you're using docker and VS Code, you can skip right to [Source Code](#source-code).
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
|
||||
## Setup
|
||||
|
||||
### West Installation
|
||||
|
||||
`west` is the [Zephyr™ meta-tool](https://docs.zephyrproject.org/2.5.0/guides/west/index.html) used to configure and build Zephyr™ applications.
|
||||
|
||||
West can be installed by using the `pip` python package manager. The [Zephyr™ instructions](https://docs.zephyrproject.org/2.5.0/guides/west/install.html#installing-west) are summarized here:
|
||||
|
||||
<Tabs
|
||||
defaultValue="linux"
|
||||
values={[
|
||||
{label: 'Linux', value: 'linux'},
|
||||
{label: 'Windows', value: 'win'},
|
||||
]}>
|
||||
<TabItem value = 'linux'>
|
||||
|
||||
```sh
|
||||
pip3 install --user -U west
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value = 'win'>
|
||||
|
||||
In `cmd.exe` as **Administrator**:
|
||||
|
||||
```sh
|
||||
pip3 install -U west
|
||||
```
|
||||
|
||||
:::note
|
||||
**For Windows, do not use the `--user` argument** that Linux uses otherwise `west` will be installed in a different location and the below instructions for adding Python `pip` will no longer apply.
|
||||
:::
|
||||
|
||||
Once `west` is installed, close Command Prompt and open a new session as a **user** for the remainder of the instructions.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::danger `pip` user packages
|
||||
If you haven't done so yet, you may need to add the Python `pip` package directory to your `PATH` otherwise your computer will not be able to find the `west` command.
|
||||
:::
|
||||
|
||||
<Tabs
|
||||
defaultValue="linux"
|
||||
values={[
|
||||
{label: 'Linux', value: 'linux'},
|
||||
{label: 'Windows', value: 'win'},
|
||||
]}>
|
||||
<TabItem value = 'linux'>
|
||||
Run the following commands:
|
||||
|
||||
```sh
|
||||
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value = 'win'>
|
||||
|
||||
1. See the [Environment Variables](#environment-variables) section on how to get to the Environment Variables page.
|
||||
2. Under "System variables" select the "Path" variable. Click "Edit..." and then "New" to add the directory where your `west.exe` is located. By default this should be `C:\Python##\Scripts` where ## is your Python version number.
|
||||
3. Close Command Prompt and open a new session for the changes to take effect, or run `refreshenv`.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Toolchain Installation
|
||||
|
||||
The toolchain provides the compiler, linker, etc., necessary to build for the target
|
||||
platform.
|
||||
|
||||
<OsTabs>
|
||||
<TabItem value="debian">
|
||||
|
||||
#### 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.13.2
|
||||
wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-linux-x86_64-setup.run" && \
|
||||
sh "zephyr-toolchain-arm-${ZSDK_VERSION}-linux-x86_64-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \
|
||||
rm "zephyr-toolchain-arm-${ZSDK_VERSION}-linux-x86_64-setup.run"
|
||||
```
|
||||
|
||||
The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults should normally work as expected.
|
||||
Return to this guide once you are finished with each section.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="raspberryos">
|
||||
|
||||
Because Raspberry OS (Raspbian) runs on the same architecture (but different ABI) as the keyboard MCUs,
|
||||
the operating system's installed [cross compilers](https://docs.zephyrproject.org/2.5.0/getting_started/toolchain_other_x_compilers.html) can be used to target the different ABI.
|
||||
#### Install Base Dependencies
|
||||
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html) and follow the instructions for Ubuntu under these sections:
|
||||
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.2.0/develop/getting_started/index.html#install-dependencies)
|
||||
|
||||
Return to this guide once you are finished with each section.
|
||||
|
||||
#### 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.2.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:
|
||||
|
||||
|
|
@ -298,7 +95,7 @@ First, the cross compiler should be installed:
|
|||
sudo apt install gcc-arm-none-eabi
|
||||
```
|
||||
|
||||
Next, we'll configure Zephyr™ with some extra environment variables needed to find the cross compiler by adding the following to `~/.zephyrrc`:
|
||||
Next, we'll configure Zephyr with some [environment variables](https://docs.zephyrproject.org/3.2.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
|
||||
|
|
@ -308,50 +105,83 @@ export CROSS_COMPILE=/usr/bin/arm-none-eabi-
|
|||
</TabItem>
|
||||
<TabItem value="fedora">
|
||||
|
||||
#### 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.13.2
|
||||
wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-linux-x86_64-setup.run" && \
|
||||
sh "zephyr-toolchain-arm-${ZSDK_VERSION}-linux-x86_64-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \
|
||||
rm "zephyr-toolchain-arm-${ZSDK_VERSION}-linux-x86_64-setup.run"
|
||||
```
|
||||
|
||||
The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults should normally work as expected.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
#### GNU ARM Embedded
|
||||
|
||||
Since the Zephyr™ SDK is not available for Windows, we recommending following the [Zephyr documentation](https://docs.zephyrproject.org/2.5.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded) to install a GNU ARM Embedded build. Note the warnings regarding installing the toolchain into a path with spaces, and make sure to follow the steps to add the environment variables which are also summarized with screenshots in the [Environment Variables](#environment-variables) section below.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac">
|
||||
|
||||
#### GNU ARM Embedded
|
||||
|
||||
Since the Zephyr™ SDK is not available for macOS, we recommending following the steps to install the GNU ARM Embedded toolchain:
|
||||
|
||||
```
|
||||
brew install --cask gcc-arm-embedded
|
||||
```
|
||||
Follow Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.2.0/develop/getting_started/installation_linux.html) documentation for Fedora.
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
|
||||
:::note
|
||||
If you intend to build firmware straight away, make sure to correctly setup the current shell.
|
||||
### Install West
|
||||
|
||||
Notes on setting this up can be found in the [Environment Variables](#environment-variables) section.
|
||||
The transient instructions can be used to setup the current shell, and the automatic instructions can setup any newly made shells automatically.
|
||||
`west` is the [Zephyr® Project's meta-tool](https://docs.zephyrproject.org/3.2.0/develop/west/index.html) used to configure and build Zephyr OS applications.
|
||||
|
||||
The transient instructions must be run to build firmware using the current shell.
|
||||
:::
|
||||
West can be installed by using the `pip` python package manager. The [Zephyr™ instructions](https://docs.zephyrproject.org/3.2.0/develop/west/install.html) are summarized here:
|
||||
|
||||
### Source Code
|
||||
<Tabs
|
||||
defaultValue="linux"
|
||||
groupId="python-os"
|
||||
values={[
|
||||
{label: 'Linux', value: 'linux'},
|
||||
{label: 'Windows', value: 'win'},
|
||||
{label: 'macOS', value: 'mac'},
|
||||
]}>
|
||||
<TabItem value="linux">
|
||||
|
||||
Install west:
|
||||
|
||||
```sh
|
||||
pip3 install --user -U west
|
||||
```
|
||||
|
||||
Verify that west is installed:
|
||||
|
||||
```sh
|
||||
west --version
|
||||
```
|
||||
|
||||
This should print a message like "West version: v0.14.0". If it prints an error instead, make sure `~/.local/bin` is on your `PATH` environment variable. You can add it with these commands:
|
||||
|
||||
```sh
|
||||
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
Install west:
|
||||
|
||||
```sh
|
||||
pip3 install -U west
|
||||
```
|
||||
|
||||
Verify that west is installed:
|
||||
|
||||
```sh
|
||||
west --version
|
||||
```
|
||||
|
||||
This should print a message like "West version: v0.14.0". If it prints an error instead, make sure that the Python scripts directory is on your `PATH` environment variable. You can add it by opening a PowerShell window and running the following commands:
|
||||
|
||||
```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">
|
||||
|
||||
Install west:
|
||||
|
||||
```sh
|
||||
pip3 install -U west
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## 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:
|
||||
|
||||
|
|
@ -359,13 +189,13 @@ Next, you'll need to clone the ZMK source repository if you haven't already. Nav
|
|||
git clone https://github.com/zmkfirmware/zmk.git
|
||||
```
|
||||
|
||||
### Initialize & Update Zephyr Workspace
|
||||
## 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
|
||||
### Step into the repository
|
||||
|
||||
<OsTabs>
|
||||
<TabItem value="debian">
|
||||
|
|
@ -421,19 +251,13 @@ All subsequent steps must be performed from the VS Code terminal _inside_ the co
|
|||
</TabItem>
|
||||
</OsTabs>
|
||||
|
||||
#### Initialize West
|
||||
### Initialize the Application
|
||||
|
||||
```sh
|
||||
west init -l app/
|
||||
```
|
||||
|
||||
:::caution Command Not Found?
|
||||
If you encounter errors like `command not found: west` then your `PATH` environment variable is likely
|
||||
missing the Python 3 user packages directory. See the [West Build Command](#west-build-command)
|
||||
section again for links to how to do this
|
||||
:::
|
||||
|
||||
#### Update To Fetch Modules
|
||||
### Update to Fetch Modules
|
||||
|
||||
```sh
|
||||
west update
|
||||
|
|
@ -449,103 +273,45 @@ If you're using Docker, you're done with setup! You must restart the container a
|
|||
Once your container is restarted, proceed to [Building and Flashing](development/build-flash.md).
|
||||
:::
|
||||
|
||||
#### Export Zephyr™ Core
|
||||
### Export Zephyr CMake package
|
||||
|
||||
This allows CMake to load the code needed to build ZMK.
|
||||
|
||||
```sh
|
||||
west zephyr-export
|
||||
```
|
||||
|
||||
#### Install Zephyr Python Dependencies
|
||||
### Install Zephyr Python Dependencies
|
||||
|
||||
Some additional Python dependencies are listed in Zephyr's `scripts/requirements.txt` file.
|
||||
|
||||
<Tabs
|
||||
defaultValue="linux"
|
||||
groupId="python-os"
|
||||
values={[
|
||||
{label: 'Linux', value: 'linux'},
|
||||
{label: 'Windows', value: 'win'},
|
||||
{label: 'macOS', value: 'mac'},
|
||||
]}>
|
||||
<TabItem value="linux">
|
||||
|
||||
```sh
|
||||
pip3 install --user -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
<Tabs
|
||||
defaultValue="win"
|
||||
values={[
|
||||
{label: 'Windows', value: 'win'},
|
||||
{label: 'Other OS', value: 'other'},
|
||||
]}>
|
||||
<TabItem value = 'win'>
|
||||
|
||||
#### For GNU ARM Embedded on Windows
|
||||
|
||||
On Windows, only two environment variables need to be set for ZMK to build properly: `ZEPHYR_TOOLCHAIN_VARIANT` and `GNUARMEMB_TOOLCHAIN_PATH`.
|
||||
|
||||
1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it.
|
||||
|
||||
|
||||
|
||||
2. Click 'Environment Variables...'.
|
||||
|
||||
|
||||
|
||||
3. Click "New..." under System variables to create a new system variable.
|
||||
|
||||
|
||||
|
||||
4. Set the variable name to 'ZEPHYR_TOOLCHAIN_VARIANT' and value to 'gnuarmemb'. Click OK to save.
|
||||
|
||||
|
||||
|
||||
5. Create another variable with variable name 'GNUARMEMB_TOOLCHAIN_PATH' and value set to wherever you installed your toolchain. **Make sure this path does not contain any spaces.** If it does, rename the folder and update here. Click OK to save.
|
||||
|
||||
|
||||
|
||||
6. Close Command Prompt and reopen, or run `refreshenv` to apply the changes.
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value = 'other'>
|
||||
|
||||
#### For Zephyr
|
||||
|
||||
By default, the Zephyr™ SDK will create a file named `~/.zephyrrc` with the correct environment variables to build ZMK.
|
||||
We suggest two main [options](https://docs.zephyrproject.org/2.5.0/guides/env_vars.html#option-3-using-zephyrrc-files) for how to load those settings.
|
||||
|
||||
##### Per Shell
|
||||
|
||||
To load the Zephyr environment properly for just one transient shell, run the following from your ZMK checkout directory:
|
||||
|
||||
```
|
||||
source 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.
|
||||
|
||||
<Tabs
|
||||
groupId="shell"
|
||||
defaultValue="bash"
|
||||
values={[
|
||||
{label: 'bash', value: 'bash'},
|
||||
{label: 'zsh', value: 'zsh'},
|
||||
]
|
||||
}>
|
||||
|
||||
<TabItem value="bash">
|
||||
|
||||
```
|
||||
cat ~/.zephyrrc >> ~/.bashrc
|
||||
pip3 install --user -r zephyr/scripts/requirements.txt
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
<TabItem value="zsh">
|
||||
|
||||
```
|
||||
cat ~/.zephyrrc >> ~/.zshrc
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements.txt
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac">
|
||||
|
||||
</Tabs>
|
||||
|
||||
</TabItem>
|
||||
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements.txt
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue