kb01/zmk
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated pages based on the review

Browse source
This commit is contained in:
Nicolas Munnich 2024-05-21 12:42:20 +02:00
parent 5ddf0e323b
commit 57b329a52e
12 changed files with 109 additions and 300 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/blog/2021-07-17-zephyr-2-5.md
View file

@ -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/getting-started) 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

2
docs/blog/2022-04-02-zephyr-3-0.md
View file

@ -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/getting-started) 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

2
docs/blog/2023-04-06-zephyr-3-2.md
View file

@ -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/getting-started) 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

2
docs/blog/2024-02-09-zephyr-3-5.md
View file

@ -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/getting-started) 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

2
docs/docs/customization.md
View file

@ -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/getting-started.md) and
It is also possible to build firmware locally on your computer by following the [toolchain setup](development/setup) 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).
:::

4
docs/docs/development/new-shield.mdx
View file

@ -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/getting-started.md),
Using GitHub Actions to build your new firmware can save you from doing any local [development setup](./setup),
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/getting-started.md) guide first.
To build locally, be sure you've followed the [development setup](./setup) guide first.
:::
Once you've fully created the new keyboard shield definition,

13
docs/docs/development/setup/docker.md
View file

@ -4,7 +4,7 @@ sidebar_label: Docker
---
:::note
Currently the Docker approach is only documented for [VS Code](https://github.com/microsoft/vscode). While it can be replicated using [devcontainers](https://containers.dev/) this is not documented yet - contributions are welcome!
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
@ -15,15 +15,6 @@ First, you'll need to clone the ZMK source repository if you haven't already. Op
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.
:::
## Installing Development Tools
1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for your operating system.
@ -67,7 +58,7 @@ 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!
This step pulls down quite a bit of tooling, be patient!
:::
:::info

12
docs/docs/development/setup/getting-started.md → docs/docs/development/setup/index.md
View file

@ -3,16 +3,6 @@ title: Getting Started
sidebar_label: Getting Started
---
:::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.
:::
@ -28,4 +18,4 @@ The Docker approach is a self-contained development environment while the native
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](docker.md) instructions or [native](native.mdx) instructions to continue setup.
Please see the [Docker](/docs/development/setup/docker) instructions or [native](/docs/development/setup/native) instructions to continue setup.

365
docs/docs/development/setup/native.mdx
View file

@ -13,7 +13,21 @@ export const OsTabs = (props) => (
values={[
{ label: "Ubuntu", value: "ubuntu" },
{ label: "Windows", value: "win" },
{ label: "Mac OS", value: "mac" },
{ 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" },
]}
>
@ -84,11 +98,10 @@ cd zmk
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.
:::
<OsTabs>
<TabItem value="ubuntu">
<EnvTabs>
<TabItem value="venv">
<OsTabs>
<TabItem value="ubuntu">
1. Use `apt` to install Python `venv` package:
@ -96,102 +109,16 @@ These steps are very similar to Zephyr's [Get Zephyr and install Python dependen
sudo apt install python3-venv
```
2. Create a new virtual environment:
2. Create a new virtual environment and activate it:
```sh
python3 -m venv .venv
```
3. Activate the virtual environment:
```sh
source .venv/bin/activate
```
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
pip3 install west
```
5. Initialise the application (This provides ZMK with its own copy of Zephyr):
```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!
:::
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
pip3 install -r zephyr/scripts/requirements-base.txt
```
</TabItem>
<TabItem value="glob">
1. Install `west`, and make sure `~/.local/bin` is on your `PATH` environment variable:
```sh
pip3 install --user -U west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
```
2. Initialise the application (This provides ZMK with its own copy of Zephyr):
```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!
:::
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
```
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip3 install --user -r zephyr/scripts/requirements-base.txt
```
</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).
Your setup is now complete.
</TabItem>
<TabItem value="win">
<EnvTabs>
<TabItem value="venv">
1. Create a new virtual environment:
```sh
@ -216,6 +143,22 @@ python -m venv .venv
</TabItem>
</WinTermTabs>
</TabItem>
<TabItem value="mac">
1. Create a new virtual environment:
```sh
python3 -m venv .venv
```
2. Activate the virtual environment:
```sh
source .venv/bin/activate
```
</TabItem>
</OsTabs>
Once activated your shell will be prefixed with `(.venv)`. The virtual environment can be deactivated at any time by running `deactivate`.
@ -223,13 +166,13 @@ Once activated your shell will be prefixed with `(.venv)`. The virtual environme
Remember to activate the virtual environment every time you start working.
:::
3. Install west:
4. Install west:
```sh
pip install west
```
4. Initialise the application (This provides ZMK with its own copy of Zephyr):
5. Initialize the application and update to fetch modules, including Zephyr:
```sh
west init -l app/
@ -237,16 +180,16 @@ 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!
This step pulls down quite a bit of tooling, be patient!
:::
5. 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.
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
```
6. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
7. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip install -r zephyr/scripts/requirements-base.txt
@ -254,14 +197,17 @@ pip install -r zephyr/scripts/requirements-base.txt
</TabItem>
<TabItem value="glob">
<OsTabs>
<TabItem value="ubuntu">
1. Install `west`, and make sure `~/.local/bin` is on your `PATH` environment variable:
```sh
pip install -U west
pip3 install --user -U west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
```
2. Initialise the application (This provides ZMK with its own copy of Zephyr):
2. Initialize the application and update to fetch modules, including Zephyr:
```sh
west init -l app/
@ -269,7 +215,38 @@ 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!
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
```
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">
1. Install `west`, and make sure `~/.local/bin` is on your `PATH` environment variable:
```sh
pip install -U west
```
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.
@ -284,81 +261,16 @@ west zephyr-export
pip install -r zephyr/scripts/requirements-base.txt
```
</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).
:::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">
<EnvTabs>
<TabItem value="venv">
1. Create a new virtual environment:
```sh
python3 -m venv .venv
```
2. Activate the virtual environment:
```sh
source .venv/bin/activate
```
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.
:::
3. Install west:
```sh
pip3 install west
```
4. Initialise the application (This provides ZMK with its own copy of Zephyr)
```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!
:::
5. 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
```
6. Install the additional dependencies found in Zephyr's `requirements-base.txt`.
```sh
pip3 install -r zephyr/scripts/requirements-base.txt
```
</TabItem>
<TabItem value="glob">
1. Install `west`
```sh
pip3 install -U west
```
2. Initialise the application (This provides ZMK with its own copy of Zephyr)
2. Initialize the application and update to fetch modules, including Zephyr:
```sh
west init -l app/
@ -366,7 +278,7 @@ 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!
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.
@ -381,112 +293,28 @@ west zephyr-export
pip3 install -r ~/zephyrproject/zephyr/scripts/requirements-base.txt
```
</TabItem>
</OsTabs>
</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">
<EnvTabs>
<TabItem value="venv">
1. Use `apt` to install Python `venv` package:
```sh
sudo apt install python3-venv
```
2. Create a new virtual environment:
```sh
python3 -m venv .venv
```
3. Activate the virtual environment:
```sh
source .venv/bin/activate
```
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
pip3 install west
```
5. Initialise the application (This provides ZMK with its own copy of Zephyr):
```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!
:::
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
pip3 install -r zephyr/scripts/requirements-base.txt
```
</TabItem>
<TabItem value="glob">
1. Install `west`, and make sure `~/.local/bin` is on your `PATH` environment variable:
```sh
pip3 install --user -U west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
```
2. Initialise the application (This provides ZMK with its own copy of Zephyr):
```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!
:::
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
```
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
```sh
pip3 install --user -r ~/zephyrproject/zephyr/scripts/requirements-base.txt
```
</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).
## 5. Install Cross-Compile Toolchain
#### 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.
@ -503,7 +331,8 @@ export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
export CROSS_COMPILE=/usr/bin/arm-none-eabi-
```
Your setup is now complete.
</TabItem>
</OsTabs>
</OsNoteTabs>
Your setup is now complete.

2
docs/docusaurus.config.js
View file

@ -80,7 +80,7 @@ module.exports = {
},
{
label: "Development",
to: "docs/development/setup/getting-started",
to: "docs/development/setup",
},
],
},

2
docs/sidebars.js
View file

@ -81,7 +81,7 @@ module.exports = {
label: "Setup",
collapsed: false,
items: [
"development/setup/getting-started",
"development/setup/index",
"development/setup/docker",
"development/setup/native",
],

1
docs/static/_redirects vendored
View file

@ -1 +0,0 @@
/docs/development/setup /docs/development/setup/getting-started