From a1e81d4db30a022623fbdd4950c316c4c17fd854 Mon Sep 17 00:00:00 2001 From: Pauiii <28485602+Pauiii@users.noreply.github.com> Date: Fri, 25 Oct 2024 19:21:38 +0200 Subject: [PATCH] docs: Apply suggestions from code review. --- .../local-toolchain/build-flash.mdx | 71 ++++++++----------- .../local-toolchain/setup/container.mdx | 15 +--- 2 files changed, 32 insertions(+), 54 deletions(-) diff --git a/docs/docs/development/local-toolchain/build-flash.mdx b/docs/docs/development/local-toolchain/build-flash.mdx index 33cd0d71b65..982d00f4bd4 100644 --- a/docs/docs/development/local-toolchain/build-flash.mdx +++ b/docs/docs/development/local-toolchain/build-flash.mdx @@ -72,55 +72,42 @@ with an onboard MCU or one that uses an MCU board add-on. 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. There are two possible ways to do that. +its invocations. - - - The simplest way to use CMake arguments is by adding `--` after the - `west build` command and listing them afterward. For example, the - above-shown command for building a keyboard with an MCU board add-on uses - them in the form of `-DSHIELD=kyra_left`. +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: - :::tip - Once the first generation of the build directory using one-time CMake - arguments is done, you can execute subsequent builds by using: +```sh +west build -b planck_rev6 -- -DCONFIG_ZMK_SLEEP=y +``` - ```sh - west build -d - ``` - ::: +:::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: - - - The `west build` command can be configured using - [`west config`](https://docs.zephyrproject.org/3.5.0/develop/west/config.html#west-config-cmd). - This makes it possible to add permanent CMake arguments, which are invoked - whenever a new build system is generated. To do this, we make use of its - `build.cmake-args` configuration option. +```sh +west build -d +``` - ```sh - west config build.cmake-args -- -DSHIELD=kyra_left - ``` +::: - For adding multiple arguments a string can be used: +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 -DZMK_CONFIG=/absolute/path/to/zmk-config" - ``` +```sh +west config build.cmake-args -- -DSHIELD=kyra_left +``` - :::note - New build systems are only generated with `west build` when they are - currently is non-available. Therefore, either delete the build directory or - do a **pristine build**. - ::: +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 @@ -173,9 +160,9 @@ 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) +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 labelled `config` +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 diff --git a/docs/docs/development/local-toolchain/setup/container.mdx b/docs/docs/development/local-toolchain/setup/container.mdx index dd857ba6624..56209b5035a 100644 --- a/docs/docs/development/local-toolchain/setup/container.mdx +++ b/docs/docs/development/local-toolchain/setup/container.mdx @@ -50,7 +50,7 @@ git clone https://github.com/zmkfirmware/zmk.git :::warning Please follow the installation instructions carefully. If you do not have - an working **Podman machine**, executing the commands below won't be + a working **Podman machine**, executing the commands below won't be possible. ::: @@ -59,8 +59,8 @@ git clone https://github.com/zmkfirmware/zmk.git ## Creating Volumes -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. +To build from a `zmk-config` or with additional modules, it is necessary to +first make them available by creating volumes. -:::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. -::: :::note When changing the configuration or modules directory, new volumes have to be @@ -257,11 +255,6 @@ west init -l app/ # Initialization west update # Update modules ``` -:::tip -This step pulls down quite a bit of tooling, be patient! -::: - -:::note If you are using a Docker-based approach, you have to restart the container at this point. Stopping it is possible with these commands. @@ -269,5 +262,3 @@ this point. Stopping it is possible with these commands. docker ps # List containers docker stop "" # Stop the container ``` - -:::