Skip to content

Commit

Permalink
docs: Adjust docker documentation.
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@Pauiii
Pauiii committed Oct 16, 2024
1 parent 0e9a09d commit 40313d3
Show file tree
Hide file tree
Showing 2 changed files with 130 additions and 135 deletions.
21 changes: 10 additions & 11 deletions docs/docs/development/local-toolchain/build-flash.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,23 +5,22 @@ sidebar_label: Building and Flashing

## Building

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.
From here on, building and flashing ZMK should all be done from the `app/`
subdirectory of the ZMK checkout:

:::warning
From here on the process for building and flashing varies based on the method
you're using:

- **[VS Code](setup/docker.mdx)/[Native](setup/native.mdx)**:
Execute the commands from within the `app/` subdirectory of the ZMK checkout.
- **[Dev Container CLI](setup/docker.mdx)**:
Add `-s /absolute/path/to/zmk/app` to the `west` command.
```sh
cd app
```

:::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?`
:::

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.

### Keyboard (Shield) + MCU Board

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)
Expand Down
244 changes: 120 additions & 124 deletions docs/docs/development/local-toolchain/setup/docker.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sidebar_label: Docker
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

### Source Code
## 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`
Expand All @@ -16,175 +16,171 @@ directory in, then run the following command:
git clone https://github.com/zmkfirmware/zmk.git
```

### Docker Setup
## Installing Development Tools

<Tabs defaultValue="vsCode"
<Tabs groupId="dev-container"
defaultValue="vsCode"
values={[
{label: 'VS Code', value: 'vsCode'},
{label: 'Dev Container CLI', value: 'cli'}
]}>
<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).
:::
:::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).

#### Installing Development Tools
</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>
</Tabs>

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).
## Creating Volumes

#### Initialize & Update Zephyr Workspace
In case you have a `zmk-config` or want to build with additional modules, it is
necessary to first make them available by creating volumes. When setting up the
Dev Container, those then will automatically be mounted to the Docker container.

Open the `zmk` checkout directory in VS Code. The repository includes a
configuration for containerized development. Therefore, an alert will pop up:
<Tabs
defaultValue="config"
values={[
{ label: "Zmk-Config", value: "config" },
{ label: "Modules", value: "modules" },
]}
>
<TabItem value="config">

![VS Code Dev Container Configuration Alert](../../../assets/dev-setup/vscode_devcontainer.png)
```sh
docker volume create --driver local -o o=bind -o type=none \ -o
device="/absolute/path/to/zmk-config/" zmk-config
```

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`:
</TabItem>
<TabItem value="modules">

- **Windows/Linux**: `Ctrl + Shift + P`
- **MacOs**: `Cmd + Shift + P`
```sh
docker volume create --driver local -o o=bind -o type=none -o \
device="/absolute/path/to/zmk-modules/parent/" zmk-modules
```

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>
</Tabs>

:::caution
The following step and any future [build commands](../build-flash.mdx) must be
executed from the VS Code terminal _inside_ the container.
:::tip
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.
:::

Initialize the application and update modules, including Zephyr:
:::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.

```sh
west init -l app/
west update
docker container ps # List containers
docker container stop "<container-id>" # Stop the container
docker container rm "<container-id>" # Remove the container

docker volume ls # List volumes
docker volume rm "<volume-name>" # Remove volume
```

:::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 this is to
close the VS Code window, verify that the container has stopped in the Docker
Dashboard, and reopen the container with VS Code.
## Initialize Dev Container

Your setup is complete once your container has restarted.
:::
<Tabs groupId="dev-container"
defaultValue="vsCode"
values={[
{label: 'VS Code', value: 'vsCode'},
{label: 'Dev Container CLI', value: 'cli'}
]}>
<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">
#### Installing Development Tools
First, make sure that the
[Dev Container CLI](https://github.com/devcontainers/cli) is installed by
running:

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).
```sh
devcontainer --version
```

#### Initialize & Update Zephyr Workspace
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:

Open up your Terminal and make sure that the
[Dev Container CLI](https://github.com/devcontainers/cli) is installed by
running:
```sh
devcontainer up --workspace-folder "/absolute/path/to/zmk"
```

```sh
devcontainer --version
```
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!**

To be able to execute commands, 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, which is available for all commands and will automatically look up the
file relative to the path. Therefore, the container can be started by executing:
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
devcontainer up --workspace-folder "/absolute/path/to/zmk"
```
```sh
docker container ps # List containers
docker exec -w /workspaces/zmk -it <container_id> /bin/bash # Connect
```

</TabItem>
</Tabs>

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!**
## Configure Zephyr Workspace

Once the command is finished, the development environment is available.
Furthermore, the path is mounted under `/workspaces/zmk/`. It can then be used
to initialize the application and update modules, including Zephyr.
:::caution
The following step and any future [build commands](../build-flash.mdx) must be
executed from the command line _inside_ the container.
:::

```sh
devcontainer exec --workspace-folder "/absolute/path/to/zmk" \
west init -l "/workspaces/zmk/app"
devcontainer exec --workspace-folder "/absolute/path/to/zmk" \
west update
west init -l app/ # Initialization
west update # Update modules
```

:::tip
This step pulls down quite a bit of tooling, be patient!
:::

:::info
You must restart the container at this point. This can be done by using:
After this is done, you have to restart the container using the following
commands:

```sh
docker container ps # List active containers
docker container ps # List containers
docker container stop "<container-id>" # Stop the container
```

Your setup is complete once your container has been restarted.
:::

</TabItem>
</Tabs>

### Volume Setup

In case you have a `zmk-config` or want to build with additional modules, it is
necessary to first make those available to the Docker container. This can be
done by mounting them as volumes.

But before you do so, first check that neither ZMK related containers nor the
`zmk-config` and `zmk-modules` volumes exist. This can be done with:

```sh
docker container ps # List active containers
docker container stop "<container-id>" # Stop the container
docker container rm "<container-id>" # Remove the container

docker volume ls # List volumes
docker volume rm "<volume-name>" # Remove volume
```

:::note
You can also use `docker container prune` to remove all containers if no others
are running.
:::

<Tabs
defaultValue="config"
values={[
{ label: "Zmk-Config", value: "config" },
{ label: "Modules", value: "modules" },
]}
>
<TabItem value="config">
```sh docker volume create --driver local -o o=bind -o type=none \ -o
device="/absolute/path/to/zmk-config/" zmk-config ```
</TabItem>
<TabItem value="modules">
```sh docker volume create --driver local -o o=bind -o type=none -o \
device="/absolute/path/to/zmk-modules/parent/" zmk-modules ```
</TabItem>
</Tabs>
:::tip
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.
:::

0 comments on commit 40313d3

Please sign in to comment.