zoriya/zmk
1
0
Fork 0
mirror of https://github.com/zoriya/zmk.git synced 2025-12-06 06:56:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Devcontainers-cli enhancement (#2548)

Browse Source 
* docs: Split local toolchain setup for Docker in two separated approaches.

This includes adding a new dropdown for Docker which lists overall steps
that have to be done when setting up the environment. Furthermore, the
previous documentation is no listed under VSCode and new documentation
for the Devcontainer CLI has been added.

Since the described approaches for VS Code and Dev Container CLI varied
quiet a bit a more unified way of setting them up was added. Due to
that, the documentation for building and flashing could be simplified as
well.

* docs: Update documentation for building and flashing for devcontainers.

Moved information about creating volumes for Docker containers into the
overall Docker setup documentation. Add warning for changing build
directory or adding options for building at the top of the page.

* feat(devcontainers): Add new volume for mounting modules.

---------

Co-authored-by: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com>
This commit is contained in:
Pauiii
2024-10-27 20:17:41 +01:00
committed by GitHub
parent 7d8dd64cdc
commit cb5e605906
6 changed files with 381 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.devcontainer/devcontainer.json
View File

@@ -9,6 +9,7 @@
"mounts": [
"type=volume,source=zmk-root-user,target=/root",
"type=volume,source=zmk-config,target=/workspaces/zmk-config",
"type=volume,source=zmk-modules,target=/workspaces/zmk-modules",
"type=volume,source=zmk-zephyr,target=${containerWorkspaceFolder}/zephyr",
"type=volume,source=zmk-zephyr-modules,target=${containerWorkspaceFolder}/modules",
"type=volume,source=zmk-zephyr-tools,target=${containerWorkspaceFolder}/tools"

130
docs/docs/development/local-toolchain/build-flash.mdx
View File

@@ -3,20 +3,55 @@ title: Building and Flashing
sidebar_label: Building and Flashing
---
## Building
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout:
From here on, building and flashing ZMK should all be done from the `app/`
subdirectory of the ZMK checkout:
```sh
cd app
```
To build for your particular keyboard, the behavior varies slightly depending on if you are building for a keyboard with
an onboard MCU, or one that uses an MCU board addon.
:::warning
If this is not done, you will encounter errors such as: `ERROR: source directory
"." does not contain a CMakeLists.txt; is this really what you want to build?`
:::
### Keyboard (Shield) + MCU Board
## Building
ZMK treats keyboards that take an MCU addon board as [shields](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html)
Building a particular keyboard is done using the
[`west build`](https://docs.zephyrproject.org/3.5.0/develop/west/build-flash-debug.html#building-west-build)
command. Its usage slightly changes depending on if your build is for a keyboard
with an onboard MCU or one that uses an MCU board add-on.
<Tabs defaultValue="onboardMcu"
values={[
{label: 'Onboard MCU', value: 'onboardMcu'},
{label: 'Addon MCU', value: 'addonMcu'}
]}>
<TabItem value="onboardMcu">
Keyboards with onboard MCU chips are simply treated as the
[board](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html)
as far as Zephyr™ is concerned.
Given the following:
- Keyboard: Planck (rev6)
- Keymap: default
you can build ZMK with the following:
```sh
west build -b planck_rev6
```
</TabItem>
<TabItem value="addonMcu">
ZMK treats keyboards that take an MCU addon board as
[shields](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html),
and treats the smaller MCU board as the true
[board](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html).
Given the following:
@@ -30,19 +65,48 @@ You can build ZMK with the following:
west build -b proton_c -- -DSHIELD=kyria_left
```
### Keyboard With Onboard MCU
</TabItem>
</Tabs>
Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html) as far as Zephyr™ is concerned.
### CMake Arguments
Given the following:
For creating a build system, the `west build` command uses
[CMake](https://cmake.org/). This allows for additional arguments to be added to
its invocations.
- Keyboard: Planck (rev6)
- Keymap: default
you can build ZMK with the following:
This is done by adding `--` after the `west build` command and listing the CMake
arguments afterward. The previous section shows one example of this with
`-DSHIELD=kyria_left`. Another example use case is passing Kconfig flags:
```sh
west build -b planck_rev6
west build -b planck_rev6 -- -DCONFIG_ZMK_SLEEP=y
```
:::tip
Once the first generation of the build directory using one-time CMake arguments
is done, you can omit the CMake arguments and board selection, instead building
with the command:
```sh
west build -d <build_dir>
```
:::
You can also add permanent CMake arguments to `west build` by using the
[`west config`](https://docs.zephyrproject.org/3.5.0/develop/west/config.html#west-config-cmd)
command. These are invoked whenever a new build system is generated. To add
permanent arguments, set the `build.cmake-args` configuration option.
```sh
west config build.cmake-args -- -DSHIELD=kyra_left
```
Multiple arguments are added by assigning a string to the configuration option:
```sh
west config build.cmake-args \
-- "-DSHIELD=kyra_left -DZMK_CONFIG=/absolute/path/to/zmk-config"
```
### Pristine Building
@@ -95,40 +159,26 @@ west build -b nice_nano_v2 -- -DSHIELD=vendor_shield -DZMK_EXTRA_MODULES="C:/Use
### Building from `zmk-config` Folder
Instead of building .uf2 files using the default keymap and config files, you can build directly from your [`zmk-config` folder](../../user-setup.mdx#github-repo) by adding
`-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labelled `config` within your `zmk-config` folder.**
Instead of building .uf2 files using the default keymap and config files, you
can build using files from your [`zmk-config` folder](../../user-setup.mdx#github-repo)
by adding `-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build`
command. **Notice that this path should point to the folder labeled `config`
within your `zmk-config` folder.**
For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder on Windows 10 may look something like this:
For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder
on Windows may look something like this:
```sh
west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config"
west build -b nice_nano -- -DSHIELD=kyria_left \
-DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config"
```
:::warning
The above command must still be invoked from the `zmk/app` directory as noted above, rather than the config directory. Otherwise, you will encounter errors such as `ERROR: source directory "." does not contain a CMakeLists.txt; is this really what you want to build?`. Alternatively you can add the `-s /path/to/zmk/app` flag to your `west` command.
If your config is also a [module](../../features/modules.mdx), then you should
also add the root (the folder in which the `zephyr` folder is found) of your
`zmk-config` as an [external module to build with](#building-with-external-modules).
:::
:::warning
If your config is also a [module](../../features/modules.mdx), then you should also add the root (the folder in which the `zephyr` folder is found) of your `zmk-config` as an [external module to build with](#building-with-external-modules).
:::
In order to make your `zmk-config` folder available when building within the VSCode Remote Container, you need to create a docker volume named `zmk-config`
by binding it to the full path of your config directory. If you have run the VSCode Remote Container before, it is likely that docker has created this
volume automatically -- we need to delete the default volume before binding it to the correct path. Follow the following steps:
1. Stop the container by exiting VSCode. You can verify no container is running via the command `docker ps`.
1. Remove all the containers that are not running via the command `docker container prune`. We need to remove the ZMK container before we can delete the default `zmk-config` volume referenced by it. If you do not want to delete all the containers that are not running, you can find the id of the ZMK container and use `docker rm` to delete that one only.
1. Remove the default volume via the command `docker volume rm zmk-config`.
Then you can bind the `zmk-config` volume to the correct path pointing to your local [zmk-config](customization.md) folder:
```sh
docker volume create --driver local -o o=bind -o type=none -o \
device="/full/path/to/your/zmk-config/" zmk-config
```
Now start VSCode and rebuild the container after being prompted. You should be able to see your zmk-config mounted to `/workspaces/zmk-config` inside the container. So you can build your custom firmware with `-DZMK_CONFIG="/workspaces/zmk-config/config"`.
## Flashing
The above build commands generate a UF2 file in `build/zephyr` (or

264
docs/docs/development/local-toolchain/setup/container.mdx Normal file
View File

@@ -0,0 +1,264 @@
---
title: Container
sidebar_label: Container
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
## 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
<Tabs groupId="container"
defaultValue="vsCode"
values={[
{label: 'VS Code', value: 'vsCode'},
{label: 'Dev Container CLI', value: 'cli'},
{label: 'Podman', value: 'podman'}
]}>
<TabItem value="vsCode">
:::note
This approach is 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).
:::
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).
</TabItem>
<TabItem value="cli">
1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop)
for your operating system.
2. Install the [Dev Container CLI](https://github.com/devcontainers/cli).
</TabItem>
<TabItem value="podman">
1. Install Podman for your operating system:
- [Podman CLI](https://podman.io/docs/installation)
- [Podman Desktop](https://podman-desktop.io/docs/installation)
:::warning
Please follow the installation instructions carefully. If you do not have
a working **Podman machine**, executing the commands below won't be
possible.
:::
</TabItem>
</Tabs>
## Creating Volumes
To build from a `zmk-config` or with additional modules, it is necessary to
first make them available by creating volumes.
<Tabs
groupId="container"
defaultValue="vsCode"
values={[
{ label: "Docker", value: "vsCode" },
{ label: "Podman", value: "podman" },
]}
>
<TabItem value="vsCode">
When setting up the container, either using
[VS Code](https://code.visualstudio.com/) or the
[Dev Container CLI](https://github.com/devcontainers/cli), the volumes will
automatically be mounted.
#### Zmk-Config
```sh
docker volume create --driver local -o o=bind -o type=none \
-o device="/absolute/path/to/zmk-config/" zmk-config
```
#### Modules
```sh
docker volume create --driver local -o o=bind -o type=none \
-o device="/absolute/path/to/zmk-modules/parent/" zmk-modules
```
</TabItem>
<TabItem value="podman">
#### Zmk-Config
```sh
podman volume create --driver local -o o=bind -o type=none \
-o device="/absolute/path/to/zmk-config/" zmk-config
```
#### Modules
```sh
podman volume create --driver local -o o=bind -o type=none \
-o device="/absolute/path/to/zmk-modules/parent/" zmk-modules
```
</TabItem>
</Tabs>
Once this is done, you can refer to the `zmk-config` with
`/workspace/zmk-config` and `/workspace/zmk-modules` to the modules instead of
using their full path like it is shown in the
[build commands](../build-flash.mdx), since these are the locations they were
mounted to in the container.
:::note
When changing the configuration or modules directory, new volumes have to be
created and mounted. Accordingly, you first have to remove the old ones.
<Tabs
groupId="container"
defaultValue="vsCode"
values={[
{ label: "Docker", value: "vsCode" },
{ label: "Podman", value: "podman" },
]}
>
<TabItem value="vsCode">
```sh
docker ps # List containers
docker stop "<container-id>" # Stop the container
docker rm "<container-id>" # Remove the container
docker volume ls # List volumes
docker volume rm "<volume-name>" # Remove volume
```
</TabItem>
<TabItem value="podman">
```sh
podman ps # List containers
podman stop "<container-id>" # Stop the container
podman rm "<container-id>" # Remove the container
podman volume ls # List volumes
podman volume rm "<volume-name>" # Remove volume
```
</TabItem>
</Tabs>
:::
## Initialize Container
<Tabs groupId="container"
defaultValue="vsCode"
values={[
{label: 'VS Code', value: 'vsCode'},
{label: 'Dev Container CLI', value: 'cli'},
{label: 'Podman', value: 'podman'}
]}>
<TabItem value="vsCode">
Open the `zmk` checkout directory in VS Code. The repository includes a
configuration for containerized development. Therefore, an alert will pop
up:
![VS Code Dev Container Configuration Alert](../../../assets/dev-setup/vscode_devcontainer.png)
Click `Reopen in Container` 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 the following keys based on your
operating system and selecting `Remote: Show Remote Menu`:
- **Windows/Linux**: `Ctrl + Shift + P`
- **MacOs**: `Cmd + Shift + P`
The first time you do this on your machine, it will pull down the Docker
image from the registry and build the container. **Subsequent launches are
much faster!**
</TabItem>
<TabItem value="cli">
First, make sure that the
[Dev Container CLI](https://github.com/devcontainers/cli) is installed by
running:
```sh
devcontainer --version
```
To be able to start the [Dev Container](https://containers.dev/), the
[Dev Container CLI](https://github.com/devcontainers/cli) has to know where
the `devcontainer.json` is located. This can be done using the
`--workspace-folder` option:
```sh
devcontainer up --workspace-folder "/absolute/path/to/zmk"
```
The first time you do this on your machine, it will pull down the Docker
image from the registry and build the container. **Subsequent launches are
much faster!**
Once the container is running, you can connect to it by using its container
ID. This allows you to execute commands inside the container:
```sh
docker ps # List containers
docker exec -w /workspaces/zmk -it <container_id> /bin/bash # Connect
```
</TabItem>
<TabItem value="podman">
First, make sure that Podman is installed by running:
```sh
podman --version
```
Since Podman is largely compatible with Docker, it is possible to use the
Dockerfile provided for use with Dev Containers for building a container
image.
```sh
podman build -t <container-name> -f Dockerfile </path/to/.devcontainer>
```
Once this is done, the container can be started with the `podman run`
command. Depending on which volumes you are using, you might have to remove
mounting options.
```sh
podman run -it --rm \
--security-opt label=disable \
--workdir /workspaces/zmk \
-v /path/to/zmk:/workspaces/zmk \
-v /path/to/zmk-config:/workspaces/zmk-config \ # Removeable
-v /path/to/zmk-modules:/workspaces/zmk-modules \ # Removeable
-p 3000:3000 \
<container-name> /bin/bash
```
</TabItem>
</Tabs>
## Configure Zephyr Workspace
:::caution
The following step and any future [build commands](../build-flash.mdx) must be
executed from the command line _inside_ the container.
:::
```sh
west init -l app/ # Initialization
west update # Update modules
```
If you are using a Docker-based approach, you have to restart the container at
this point. Stopping it is possible with these commands.
```sh
docker ps # List containers
docker stop "<container-id>" # Stop the container
```

53
docs/docs/development/local-toolchain/setup/docker.md
View File

@@ -1,53 +0,0 @@
---
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:
![VS Code Dev Container Configuration Alert](../../../assets/dev-setup/vscode_devcontainer.png)
Click `Reopen in Container` in order to reopen the VS Code with the running container. 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/local-toolchain/setup/index.md
View File

@@ -4,17 +4,27 @@ 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.
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](docker.md): \
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.
- [Docker or Podman](container.mdx): \
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 a container; the image has the toolchain installed and
set up to use.
- [Native](native.mdx): \
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.
This uses your operating system directly. Usually runs slightly faster than
the container 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 [container](container.mdx) or [native](native.mdx) instructions
to continue the setup.

2
docs/sidebars.js
View File

@@ -157,7 +157,7 @@ module.exports = {
},
collapsed: true,
items: [
"development/local-toolchain/setup/docker",
"development/local-toolchain/setup/container",
"development/local-toolchain/setup/native",
],
},