feat(docs): Improve the toolchain setup page (#2272)
Split the toolchain setup into separate docker and native pages and improve instructions to better refer to Zephyr docs in certain steps. Also refactor to improve consistency and add virtualenv instructions. --------- Co-authored-by: KemoNine <mcrosson@kemonine.info> Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com>
This commit is contained in:
Nicolas Munnich
GitHub
parent
2d96f469c8
commit
308d6bce6e
@ -19,7 +19,7 @@ There's been lots of various activity in ZMK land!
|
||||
- Tons of [documentation](/docs) work.
|
||||
- Refactoring ([#73](https://github.com/zmkfirmware/zmk/pull/73), [#74](https://github.com/zmkfirmware/zmk/pull/74)) of [keymaps](/docs/features/keymaps) to make them simpler for users.
|
||||
- Mod-Tap Behavior (docs coming!) is much improved ([#69](https://github.com/zmkfirmware/zmk/pull/69)) and usable now.
|
||||
- An initial [`setup.sh`](http://localhost:3000/docs/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you.
|
||||
- An initial [`setup.sh`](/docs/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you.
|
||||
- Corne shield ([#80](https://github.com/zmkfirmware/zmk/pull/80)) shield definition was added.
|
||||
- Initial [encoder](/docs/features/encoders) support ([#61](https://github.com/zmkfirmware/zmk/pull/61)) was added.
|
||||
|
||||
|
||||
@ -61,7 +61,7 @@ Once the container has rebuilt, VS Code will be running the 2.5 Docker image.
|
||||
|
||||
The following steps will get you building ZMK locally against Zephyr 2.5:
|
||||
|
||||
- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- pull the latest ZMK `main` with `git pull` for your ZMK checkout
|
||||
- run `west update` to pull the updated Zephyr version and its dependencies
|
||||
|
||||
|
||||
@ -62,7 +62,7 @@ Once the container has rebuilt, VS Code will be running the 3.0 Docker image.
|
||||
|
||||
The following steps will get you building ZMK locally against Zephyr 3.0:
|
||||
|
||||
- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- pull the latest ZMK `main` with `git pull` for your ZMK checkout
|
||||
- run `west update` to pull the updated Zephyr version and its dependencies
|
||||
|
||||
|
||||
@ -132,7 +132,7 @@ Another persistent bug that Apple users experienced was related to crashes and p
|
||||
The long awaited locality enhancement was finally merged by [petejohanson] in [#547](https://github.com/zmkfirmware/zmk/pull/547), allowing more fine grained control of where certain behaviors are invoked. Some key improvements thanks to the changes:
|
||||
|
||||
- [RGB Underglow](/docs/features/underglow) behaviors now run globally, so enabling/disabling RGB, changing the color, animation, etc. applies to both sides of a split properly.
|
||||
- [Reset](/docs/behaviors/reset#reset)/[Bootloader](/docs/behaviors/reset#bootloader) behaviors now run wherever the key was pressed. For example, adding a `&bootloader` reference to the peripheral side of a split will now put that side of the split into the bootloader when pressed.
|
||||
- [Reset](/docs/behaviors/reset#reset)/[Bootloader](/docs/behaviors/reset#bootloader-reset) behaviors now run wherever the key was pressed. For example, adding a `&bootloader` reference to the peripheral side of a split will now put that side of the split into the bootloader when pressed.
|
||||
|
||||
#### Split Connections
|
||||
|
||||
|
||||
@ -87,7 +87,7 @@ Once the container has rebuilt, VS Code will be running the 3.2 Docker image.
|
||||
|
||||
The following steps will get you building ZMK locally against Zephyr 3.2:
|
||||
|
||||
- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- Install the latest version of `west` by running `pip3 install --user --update west`.
|
||||
- pull the latest ZMK `main` with `git pull` for your ZMK checkout
|
||||
- run `west update` to pull the updated Zephyr version and its dependencies
|
||||
|
||||
@ -70,7 +70,7 @@ Once the container has rebuilt, VS Code will be running the 3.5 Docker image.
|
||||
|
||||
The following steps will get you building ZMK locally against Zephyr 3.5:
|
||||
|
||||
- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- Install the latest version of `west` by running `pip3 install --user --update west`.
|
||||
- Pull the latest ZMK `main` with `git pull` for your ZMK checkout
|
||||
- Run `west update` to pull the updated Zephyr version and its dependencies
|
||||
|
||||
@ -46,10 +46,10 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors
|
||||
|
||||
## Reset behaviors
|
||||
|
||||
| Binding | Behavior | Description |
|
||||
| ------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `&sys_reset` | [Reset](reset.md#reset) | Resets the keyboard and re-runs the firmware flashed to the device |
|
||||
| `&bootloader` | [Bootloader](reset.md#bootloader) | Resets the keyboard and puts it into bootloader mode, allowing you to flash new firmware |
|
||||
| Binding | Behavior | Description |
|
||||
| ------------- | --------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `&sys_reset` | [Reset](reset.md#reset) | Resets the keyboard and re-runs the firmware flashed to the device |
|
||||
| `&bootloader` | [Bootloader](reset.md#bootloader-reset) | Resets the keyboard and puts it into bootloader mode, allowing you to flash new firmware |
|
||||
|
||||
## Output selection behaviors
|
||||
|
||||
|
||||
@ -40,7 +40,7 @@ If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https:
|
||||
:::
|
||||
|
||||
:::note
|
||||
It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup.mdx) and
|
||||
It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup/index.md) and
|
||||
[building instructions](development/build-flash.mdx), which includes pointers to
|
||||
[building using your `zmk-config` folder](development/build-flash.mdx#building-from-zmk-config-folder).
|
||||
:::
|
||||
|
||||
@ -554,7 +554,7 @@ Add additional bindings as necessary to match the default number of encoders on
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup.mdx),
|
||||
Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup/index.md),
|
||||
at the expense of a longer feedback loop if there are issues. To push your changes and trigger a build:
|
||||
|
||||
- Add all your pending changes with `git add .`
|
||||
@ -566,7 +566,7 @@ Once pushed, click on the "Actions" tab of the repo you created in the first ste
|
||||
### Local Build
|
||||
|
||||
:::note
|
||||
To build locally, be sure you've followed the [development setup](./setup.mdx) guide first.
|
||||
To build locally, be sure you've followed the [development setup](./setup/index.md) guide first.
|
||||
:::
|
||||
|
||||
Once you've fully created the new keyboard shield definition,
|
||||
|
||||
@ -1,322 +0,0 @@
|
||||
---
|
||||
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="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" },
|
||||
]}
|
||||
>
|
||||
{/* eslint-disable-next-line */}
|
||||
{props.children}
|
||||
</Tabs>
|
||||
);
|
||||
|
||||
This guide will show you how to set up a development environment for building ZMK locally.
|
||||
|
||||
## Install Dependencies
|
||||
|
||||
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">
|
||||
|
||||
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)
|
||||
- [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 each section.
|
||||
|
||||
</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:
|
||||
|
||||
- [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)
|
||||
- [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 each section.
|
||||
|
||||
`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">
|
||||
|
||||
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)
|
||||
- [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 each section.
|
||||
|
||||
</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:
|
||||
|
||||
- [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)
|
||||
|
||||
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.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>
|
||||
<TabItem value="fedora">
|
||||
|
||||
Follow Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) documentation for Fedora.
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
|
||||
### Install West
|
||||
|
||||
`west` is the [Zephyr® Project's meta-tool](https://docs.zephyrproject.org/3.5.0/develop/west/index.html) used to configure and build Zephyr OS applications.
|
||||
|
||||
West can be installed by using the `pip` python package manager. The [Zephyr™ instructions](https://docs.zephyrproject.org/3.5.0/develop/west/install.html) are summarized here:
|
||||
|
||||
<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:
|
||||
|
||||
```
|
||||
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="debian">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="raspberryos">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fedora">
|
||||
|
||||
```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
|
||||
If you're using Docker, you're done with setup! 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.
|
||||
|
||||
Once your container is restarted, proceed to [Building and Flashing](development/build-flash.mdx).
|
||||
:::
|
||||
|
||||
### Export Zephyr CMake package
|
||||
|
||||
This allows CMake to load the code needed to build ZMK.
|
||||
|
||||
```sh
|
||||
west zephyr-export
|
||||
```
|
||||
|
||||
### 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.txt
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements.txt
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac">
|
||||
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements.txt
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
53
docs/docs/development/setup/docker.md
Normal file
53
docs/docs/development/setup/docker.md
Normal 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:
|
||||
|
||||
|
||||
|
||||
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/setup/index.md
Normal file
20
docs/docs/development/setup/index.md
Normal 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](/docs/development/setup/docker): \
|
||||
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](/docs/development/setup/native):\
|
||||
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](/docs/development/setup/docker) instructions or [native](/docs/development/setup/native) instructions to continue setup.
|
||||
353
docs/docs/development/setup/native.mdx
Normal file
353
docs/docs/development/setup/native.mdx
Normal 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.
|
||||
@ -34,7 +34,7 @@ macOS 14.x (Sonoma) Finder may report an "Error code -36" when copying `<firmwar
|
||||
### CMake Error
|
||||
|
||||
An error along the lines of `CMake Error at (zmk directory)/zephyr/cmake/generic_toolchain.cmake:64 (include): include could not find load file:` during firmware compilation indicates that the Zephyr Environment Variables are not properly defined.
|
||||
For more information, see [toolchain setup documentation](../docs/development/setup.mdx).
|
||||
For more information, see [Zephyr's CMake Package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html).
|
||||
|
||||
### West Build Errors
|
||||
|
||||
|
||||
@ -31,6 +31,7 @@ module.exports = {
|
||||
"linker-script",
|
||||
"log",
|
||||
"powershell",
|
||||
"diff",
|
||||
],
|
||||
theme,
|
||||
darkTheme,
|
||||
@ -79,7 +80,7 @@ module.exports = {
|
||||
},
|
||||
{
|
||||
label: "Development",
|
||||
to: "docs/development/setup/",
|
||||
to: "docs/development/setup",
|
||||
},
|
||||
],
|
||||
},
|
||||
|
||||
@ -76,7 +76,16 @@ module.exports = {
|
||||
"development/clean-room",
|
||||
"development/pre-commit",
|
||||
"development/documentation",
|
||||
"development/setup",
|
||||
{
|
||||
type: "category",
|
||||
label: "Setup",
|
||||
collapsed: true,
|
||||
items: [
|
||||
"development/setup/index",
|
||||
"development/setup/docker",
|
||||
"development/setup/native",
|
||||
],
|
||||
},
|
||||
"development/build-flash",
|
||||
"development/boards-shields-keymaps",
|
||||
"development/posix-board",
|
||||
|
||||
@ -46,3 +46,7 @@
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
}
|
||||
|
||||
.secrettabs {
|
||||
display: none;
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user