Merged the changes made here with the changes made in https://github.com/mcrosson/zmk/tree/docs-setupcleanup. Also fixed some broken links in the blog.
This commit is contained in:
Nicolas Munnich
parent
dfefb74406
commit
864f45a415
18 changed files with 344 additions and 817 deletions
|
|
@ -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/getting-started) 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/getting-started) 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/getting-started) 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/getting-started) 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
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ Below is a summary of pre-defined behavior bindings and user-definable 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 |
|
||||
| `&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/getting-started.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/getting-started),
|
||||
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/getting-started) guide first.
|
||||
:::
|
||||
|
||||
Once you've fully created the new keyboard shield definition,
|
||||
|
|
|
|||
|
|
@ -1,229 +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="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).
|
||||
:::
|
||||
|
|
@ -1,26 +0,0 @@
|
|||
---
|
||||
title: Docker+VS Code Setup
|
||||
sidebar_label: Docker
|
||||
---
|
||||
|
||||
:::danger
|
||||
The Docker environment will **NOT** run on arm CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an arm CPU.
|
||||
:::
|
||||
|
||||
This setup leverages the same [Docker image used when building ZMK on GitHub](https://github.com/zmkfirmware/zmk-docker/). 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)
|
||||
|
||||
:::note Windows Users
|
||||
Please note the ZMK builds run slower (up to 3-5 minutes on slower hardware) with Docker on Windows if you don't use the WSL2 filesystem to store files. If you run into performance problems you can checkout the ZMK sources inside a WSL2 environment and run `code .` to open the sources. This can make builds run at near-native speed.
|
||||
|
||||
This approach will also need the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension installed in VS Code.
|
||||
|
||||
Files stored within WSL2 can be accessed via Windows Explorer by navigating to `\\wsl$`.
|
||||
:::
|
||||
|
||||
## ZMK Sources Setup
|
||||
|
||||
Once the above is setup you're ready to [set up the ZMK sources](/docs/development/setup/zmk).
|
||||
60
docs/docs/development/setup/docker.md
Normal file
60
docs/docs/development/setup/docker.md
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
---
|
||||
title: Docker
|
||||
sidebar_label: Docker
|
||||
---
|
||||
|
||||
:::note
|
||||
Currently the Docker approach is only documented for VSCode, Microsoft's proprietary version of [Code OSS](https://github.com/microsoft/vscode) - See [here](https://github.com/microsoft/vscode/wiki/Differences-between-the-repository-and-Visual-Studio-Code) for more info on different versions. There is an alternative approach using [devcontainers](https://containers.dev/), but this is not documented yet - contributions are welcome!
|
||||
:::
|
||||
|
||||
## 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
|
||||
|
||||
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
|
||||
|
||||
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!
|
||||
|
||||
:::note
|
||||
If the alert fails to pop up or you accidentally close it, you can perform the same action from the remote menu: `ctrl+shift+p` and invoke `Remote: Show Remote Menu`.
|
||||
:::
|
||||
|
||||
:::caution
|
||||
All subsequent steps must be performed from the VS Code terminal _inside_ the container.
|
||||
:::
|
||||
|
||||
#### Initialize West
|
||||
|
||||
```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
|
||||
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.
|
||||
:::
|
||||
|
|
@ -3,22 +3,46 @@ title: Getting Started
|
|||
sidebar_label: Getting Started
|
||||
---
|
||||
|
||||
## Environment Setup
|
||||
|
||||
There are two ways to setup the ZMK development environment: Docker+VS Code (`Docker` in the rest of the documentation) and using the operating system directly (`native` in the rest of the documentation). The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. The Docker approach is great for getting going quickly while the native approach is a bit faster but more difficult to setup initially.
|
||||
|
||||
Please see the [Docker](/docs/development/setup/docker-vscode) instructions or [native](/docs/development/setup/native) instructions to continue setup.
|
||||
|
||||
:::caution
|
||||
The Docker environment will **NOT** run on ARM CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an ARM CPU.
|
||||
:::
|
||||
|
||||
## Standard Conventions
|
||||
|
||||
:::info
|
||||
Throughout this documentation you will see commands like
|
||||
|
||||
```
|
||||
```sh
|
||||
sudo apt update
|
||||
```
|
||||
|
||||
These commands should be run in a terminal such as Bash (Linux/MacOS/Docker), PowerShell, or Command Prompt (Windows).
|
||||
:::
|
||||
|
||||
:::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.
|
||||
:::
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
:::warning
|
||||
|
||||
#### Windows Users
|
||||
|
||||
If you're using the Docker environment on Windows, you _must_ checkout the sources to a folder within `C:\Users\[your_user_here]` to avoid a potential permissions issue.
|
||||
|
||||
If you're using the WSL2 filesystem the sources should go under `~/` to avoid potential permissions issues.
|
||||
:::
|
||||
|
||||
## Environment Setup
|
||||
|
||||
There are two ways to setup the ZMK development environment:
|
||||
|
||||
- [Docker](/docs/development/setup/docker) ;
|
||||
- [Native](/docs/development/setup/native), i.e. using the operating system directly.
|
||||
|
||||
The Docker approach is a self-contained development environment while the native approach will setup your local operating system for development. 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.
|
||||
|
||||
The native approach installs the toolchain and dependencies on your system directly. This typically 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.
|
||||
|
|
|
|||
|
|
@ -1,435 +0,0 @@
|
|||
---
|
||||
title: Native Setup
|
||||
sidebar_label: Native
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
export const OsTabs = (props) => (<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="debian"
|
||||
values={[
|
||||
{label: 'Debian/Ubuntu', value: 'debian'},
|
||||
{label: 'Windows', value: 'win'},
|
||||
{label: 'macOS', value: 'mac'},
|
||||
{label: 'Raspberry OS', value: 'raspberryos'},
|
||||
{label: 'Fedora', value: 'fedora'},
|
||||
]
|
||||
}>{props.children}</Tabs>);
|
||||
|
||||
## Prerequisites
|
||||
|
||||
ZMK requires the following base packages to first be installed:
|
||||
|
||||
- Git
|
||||
- Python 3
|
||||
- `pip`
|
||||
- `wget`
|
||||
- devicetree compiler
|
||||
- CMake
|
||||
- `dfu-util`
|
||||
- Various build essentials, e.g. gcc, automake, autoconf
|
||||
|
||||
<OsTabs>
|
||||
<TabItem value="debian">
|
||||
|
||||
On Debian and Ubuntu, 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
|
||||
```
|
||||
|
||||
:::note
|
||||
Recent LTS releases of Debian and Ubuntu may include outdated CMake versions. If the output of `cmake --version` is older than 3.15, upgrade your distribution (e.g., from Ubuntu 18.04 LTS to Ubuntu 20.04 LTS), or else install CMake version 3.15 or newer manually (e.g, from Debian backports or by building from source).
|
||||
|
||||
There is also a [zephyr bug](https://github.com/zephyrproject-rtos/zephyr/issues/22060) with cmake 3.19.x. You'll need a version _below_ 3.19.
|
||||
:::
|
||||
</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
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
:::note
|
||||
Use `cmd.exe` with these instructions rather than PowerShell.
|
||||
:::
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac">
|
||||
|
||||
#### Homebrew
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
brew install cmake ninja python3 ccache dtc git wget dfu-util
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
|
||||
## Setup
|
||||
|
||||
### West Installation
|
||||
|
||||
`west` is the [Zephyr™ meta-tool](https://docs.zephyrproject.org/2.3.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/latest/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.11.4
|
||||
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 ~/.local/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 should normally work as expected.
|
||||
|
||||
</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.3.0/getting_started/toolchain_other_x_compilers.html) can be used to target the different ABI.
|
||||
|
||||
First, the cross compiler should be installed:
|
||||
|
||||
```sh
|
||||
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`:
|
||||
|
||||
```sh
|
||||
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
|
||||
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.11.4
|
||||
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 ~/.local/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 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.3.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](https://docs.zephyrproject.org/2.3.0/getting_started/toolchain_3rd_party_x_compilers.html#gnu-arm-embedded).
|
||||
|
||||
:::warning Security Controls Workaround
|
||||
|
||||
Please be sure to read the [additional setup instructions](https://docs.zephyrproject.org/2.3.0/getting_started/installation_mac.html#mac-gatekeeper) needed to address security controls found in macOS 10.15 Catalina and newer
|
||||
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
|
||||
:::note
|
||||
If you intend to build firmware straight away, make sure to correctly setup the current shell.
|
||||
|
||||
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.
|
||||
|
||||
The transient instructions must be run to build firmware using the current shell.
|
||||
:::
|
||||
|
||||
### 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.3.0/guides/env_vars.html?highlight=zephyrrc) 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
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="zsh">
|
||||
|
||||
```
|
||||
cat ~/.zephyrrc >> ~/.zshrc
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
## ZMK Sources Setup
|
||||
|
||||
Once the above is setup you're ready to [set up the ZMK sources](/docs/development/setup/zmk).
|
||||
213
docs/docs/development/setup/native.mdx
Normal file
213
docs/docs/development/setup/native.mdx
Normal file
|
|
@ -0,0 +1,213 @@
|
|||
---
|
||||
title: Native Setup
|
||||
sidebar_label: Native
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
export const OsTabs = (props) => (
|
||||
<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="linux"
|
||||
values={[
|
||||
{ label: "Linux", value: "linux" },
|
||||
{ label: "Windows", value: "win" },
|
||||
{ label: "macOS", value: "mac" },
|
||||
{ label: "Raspberry OS", value: "raspberryos" },
|
||||
]}
|
||||
>
|
||||
{/* eslint-disable-next-line */}
|
||||
{props.children}
|
||||
</Tabs>
|
||||
);
|
||||
|
||||
First, step into the `zmk` directory that you cloned in [Getting Started](/docs/development/setup/getting-started).
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
<OsTabs>
|
||||
<TabItem value="linux">
|
||||
|
||||
## Install Zephyr and West
|
||||
|
||||
1. 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 distributions which are not based on Ubuntu.
|
||||
:::
|
||||
|
||||
2. Next, follow steps 1-4 from [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies).
|
||||
|
||||
3. ZMK comes with its own copy of Zephyr, so you don't need to add a fresh copy to a separate directory.
|
||||
|
||||
```sh
|
||||
west init -l app/
|
||||
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!
|
||||
:::
|
||||
|
||||
4. 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
|
||||
```
|
||||
|
||||
5. ZMK does not need all of the additional dependencies found in Zephyr's `requirements.txt`, but it does need those found in `requirements-base.txt`
|
||||
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
6. 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)
|
||||
|
||||
Your setup is now complete.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="win">
|
||||
|
||||
## Install Zephyr and West
|
||||
|
||||
1. 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)
|
||||
|
||||
2. Next, follow steps 1-4 from [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies).
|
||||
|
||||
3. ZMK comes with its own copy of Zephyr, so you don't need to add a fresh copy to a separate directory.
|
||||
|
||||
```sh
|
||||
west init -l app/
|
||||
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!
|
||||
:::
|
||||
|
||||
4. 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
|
||||
```
|
||||
|
||||
5. ZMK does not need all of the additional dependencies found in Zephyr's `requirements.txt`, but it does need those found in `requirements-base.txt`
|
||||
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
6. 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)
|
||||
|
||||
:::note
|
||||
`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.
|
||||
:::
|
||||
|
||||
Your setup is now complete.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac">
|
||||
|
||||
## Install Zephyr and West
|
||||
|
||||
1. 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)
|
||||
|
||||
2. Next, follow steps 1-4 from [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies).
|
||||
|
||||
3. ZMK comes with its own copy of Zephyr, so you don't need to add a fresh copy to a separate directory.
|
||||
|
||||
```sh
|
||||
west init -l app/
|
||||
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!
|
||||
:::
|
||||
|
||||
4. 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
|
||||
```
|
||||
|
||||
5. ZMK does not need all of the additional dependencies found in Zephyr's `requirements.txt`, but it does need those found in `requirements-base.txt`
|
||||
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
6. 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)
|
||||
|
||||
Your setup is now complete.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="raspberryos">
|
||||
|
||||
## Install Zephyr and West
|
||||
|
||||
1. 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)
|
||||
|
||||
2. Next, follow steps 1-4 from [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/latest/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies).
|
||||
|
||||
3. ZMK comes with its own copy of Zephyr, so you don't need to add a fresh copy to a separate directory.
|
||||
|
||||
```sh
|
||||
west init -l app/
|
||||
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!
|
||||
:::
|
||||
|
||||
4. 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
|
||||
```
|
||||
|
||||
5. ZMK does not need all of the additional dependencies found in Zephyr's `requirements.txt`, but it does need those found in `requirements-base.txt`
|
||||
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
6. 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)
|
||||
|
||||
#### 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-
|
||||
```
|
||||
|
||||
Your setup is now complete.
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
23
docs/docs/development/setup/notes.md
Normal file
23
docs/docs/development/setup/notes.md
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
### Notes about setup
|
||||
|
||||
As I cannot seem to figure out a reliable way to get comments working with Docusaurus, I'm writing notes in this file instead.
|
||||
|
||||
I don't know how accurate this is, and [Zephyr does not recommend WSL](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html), so I'm not sure this should be included.
|
||||
|
||||
:::note Windows Users
|
||||
Please note the ZMK builds run slower (up to 3-5 minutes on slower hardware) with Docker on Windows if you don't use the WSL2 filesystem to store files. If you run into performance problems you can checkout the ZMK sources inside a WSL2 environment and run `code .` to open the sources. This can make builds run at near-native speed.
|
||||
|
||||
This approach will also need the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension installed in VS Code.
|
||||
|
||||
Files stored within WSL2 can be accessed via Windows Explorer by navigating to `\\wsl$`.
|
||||
:::
|
||||
|
||||
Googling this seems to imply that there are workarounds, but I do not have access to a device to test it out. It is not included under the current docs, so I don't see a reason to include it until it is brought up by someone.
|
||||
|
||||
:::danger The Docker environment will NOT run on arm CPUs like the Raspberry Pi or Apple Silicon. You must use the native environment if using an arm CPU. :::
|
||||
|
||||
I think this is true, but I have not tested.
|
||||
|
||||
:::caution Windows Users If you're using the Docker environment on Windows, you must checkout the sources to a folder within C:\Users\[your_user_here] to avoid a potential permissions issue.
|
||||
|
||||
If you're using the WSL2 filesystem the sources should go under ~/ to avoid potential permissions issues. :::
|
||||
|
|
@ -1,102 +0,0 @@
|
|||
---
|
||||
title: ZMK Sources
|
||||
sidebar_label: ZMK Sources
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
export const OsTabs = (props) => (<Tabs
|
||||
groupId="operating-systems"
|
||||
defaultValue="docker"
|
||||
values={[
|
||||
{label: 'VS Code & Docker', value: 'docker'},
|
||||
{label: 'Native', value: 'native'},
|
||||
]
|
||||
}>{props.children}</Tabs>);
|
||||
|
||||
:::caution Windows Users
|
||||
If you're using the Docker environment on Windows, you _must_ checkout the sources to a folder within `C:\Users\[your_user_here]` to avoid a potential permissions issue.
|
||||
|
||||
If you're using the WSL2 filesystem the sources should go under `~/` to avoid potential permissions issues.
|
||||
:::
|
||||
|
||||
### 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:
|
||||
|
||||
```
|
||||
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="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!
|
||||
|
||||
:::caution
|
||||
All subsequent steps must be performed from the VS Code terminal _inside_ the container.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="native">
|
||||
|
||||
```sh
|
||||
cd zmk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</OsTabs>
|
||||
|
||||
#### Initialize West
|
||||
|
||||
```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 [Native setup](native/)
|
||||
section again for links to how to do this
|
||||
:::
|
||||
|
||||
#### 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!
|
||||
:::
|
||||
|
||||
#### Export Zephyr™ Core
|
||||
|
||||
```sh
|
||||
west zephyr-export
|
||||
```
|
||||
|
||||
#### Install Zephyr Python Dependencies
|
||||
|
||||
:::note
|
||||
This only need to be run when using the Native setup.
|
||||
:::
|
||||
|
||||
```sh
|
||||
pip3 install --user -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
|
@ -82,9 +82,8 @@ module.exports = {
|
|||
collapsed: false,
|
||||
items: [
|
||||
"development/setup/getting-started",
|
||||
"development/setup/docker-vscode",
|
||||
"development/setup/docker",
|
||||
"development/setup/native",
|
||||
"development/setup/zmk",
|
||||
],
|
||||
},
|
||||
"development/build-flash",
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue