docs: Devcontainers-cli enhancement (#2548)
* 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
GitHub
parent
7d8dd64cdc
commit
cb5e605906
6 changed files with 381 additions and 109 deletions
|
|
@ -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?`
|
||||
:::
|
||||
|
||||
### 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.
|
||||
|
||||
Given the following:
|
||||
<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.
|
||||
|
||||
- MCU Board: Proton-C
|
||||
- Keyboard PCB: kyria_left
|
||||
- Keymap: default
|
||||
Given the following:
|
||||
|
||||
You can build ZMK with 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:
|
||||
|
||||
- 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
|
||||
|
||||
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:
|
||||
:::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 -b planck_rev6
|
||||
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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue