diff options
| -rw-r--r-- | .devcontainer/devcontainer.json | 1 | ||||
| -rw-r--r-- | docs/docs/development/local-toolchain/build-flash.mdx | 140 | ||||
| -rw-r--r-- | docs/docs/development/local-toolchain/setup/container.mdx | 264 | ||||
| -rw-r--r-- | docs/docs/development/local-toolchain/setup/docker.md | 53 | ||||
| -rw-r--r-- | docs/docs/development/local-toolchain/setup/index.md | 22 | ||||
| -rw-r--r-- | docs/sidebars.js | 2 |
6 files changed, 377 insertions, 105 deletions
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index efa8c229d9..f7dc82512c 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -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" diff --git a/docs/docs/development/local-toolchain/build-flash.mdx b/docs/docs/development/local-toolchain/build-flash.mdx index 464cf34d72..982d00f4bd 100644 --- a/docs/docs/development/local-toolchain/build-flash.mdx +++ b/docs/docs/development/local-toolchain/build-flash.mdx @@ -3,46 +3,110 @@ 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?` +::: + +## Building + +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 (Shield) + MCU Board + - Keyboard: Planck (rev6) + - Keymap: default -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) + you can build ZMK with the following: -Given the following: + ```sh + west build -b planck_rev6 + ``` -- MCU Board: Proton-C -- Keyboard PCB: kyria_left -- Keymap: default + </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). -You can build ZMK with the following: + Given the following: + + - MCU Board: Proton-C + - Keyboard PCB: kyria_left + - Keymap: default + + You can build ZMK with the following: + + ```sh + west build -b proton_c -- -DSHIELD=kyria_left + ``` + + </TabItem> +</Tabs> + +### CMake Arguments + +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. + +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 proton_c -- -DSHIELD=kyria_left +west build -b planck_rev6 -- -DCONFIG_ZMK_SLEEP=y ``` -### Keyboard With Onboard MCU +:::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> +``` -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: +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. -- Keyboard: Planck (rev6) -- Keymap: default +```sh +west config build.cmake-args -- -DSHIELD=kyra_left +``` -you can build ZMK with the following: +Multiple arguments are added by assigning a string to the configuration option: ```sh -west build -b planck_rev6 +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. -::: - -:::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). +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 diff --git a/docs/docs/development/local-toolchain/setup/container.mdx b/docs/docs/development/local-toolchain/setup/container.mdx new file mode 100644 index 0000000000..56209b5035 --- /dev/null +++ b/docs/docs/development/local-toolchain/setup/container.mdx @@ -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: + +  + + 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 +``` diff --git a/docs/docs/development/local-toolchain/setup/docker.md b/docs/docs/development/local-toolchain/setup/docker.md deleted file mode 100644 index 8d9f94bc8a..0000000000 --- a/docs/docs/development/local-toolchain/setup/docker.md +++ /dev/null @@ -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: - - - -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. -::: diff --git a/docs/docs/development/local-toolchain/setup/index.md b/docs/docs/development/local-toolchain/setup/index.md index 71cc051e5a..f56a0f8284 100644 --- a/docs/docs/development/local-toolchain/setup/index.md +++ b/docs/docs/development/local-toolchain/setup/index.md @@ -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. +- [Native](native.mdx): \ + 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. diff --git a/docs/sidebars.js b/docs/sidebars.js index fa820f9079..612da6fe64 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -157,7 +157,7 @@ module.exports = { }, collapsed: true, items: [ - "development/local-toolchain/setup/docker", + "development/local-toolchain/setup/container", "development/local-toolchain/setup/native", ], }, |