Skip to content

Commit

Permalink
docs: Apply suggestions from code review.
Browse files Browse the repository at this point in the history
  • Loading branch information
Pauiii committed Oct 27, 2024
1 parent 16d399d commit a1e81d4
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 54 deletions.
71 changes: 29 additions & 42 deletions docs/docs/development/local-toolchain/build-flash.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Tabs defaultValue="oneTime"
values={[
{label: 'One-Time', value: 'oneTime'},
{label: 'Permanent', value: 'permanent'}
]}>
<TabItem value="oneTime">
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 <build_dir>
```
:::
:::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:

</TabItem>
<TabItem value="permanent">
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 <build_dir>
```

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

</TabItem>
</Tabs>
```sh
west config build.cmake-args \
-- "-DSHIELD=kyra_left -DZMK_CONFIG=/absolute/path/to/zmk-config"
```

### Pristine Building

Expand Down Expand Up @@ -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
Expand Down
15 changes: 3 additions & 12 deletions docs/docs/development/local-toolchain/setup/container.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
:::

Expand All @@ -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.

<Tabs
groupId="container"
Expand Down Expand Up @@ -105,13 +105,11 @@ necessary to first make them available by creating volumes.
</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.
:::

:::note
When changing the configuration or modules directory, new volumes have to be
Expand Down Expand Up @@ -257,17 +255,10 @@ 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.

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

:::

0 comments on commit a1e81d4

Please sign in to comment.