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 25, 2024
1 parent 16d399d commit 9d7a539
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 51 deletions.
70 changes: 30 additions & 40 deletions docs/docs/development/local-toolchain/build-flash.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -72,55 +72,45 @@ 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`.
The simplest of doing this is by adding `--` after the `west build` command and
listing the CMake arguments 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`.

:::tip
Once the first generation of the build directory using one-time CMake
arguments is done, you can execute subsequent builds by using:
:::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 -d <build_dir>
```
:::
```sh
west build -d <build_dir>
```

</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 config build.cmake-args -- -DSHIELD=kyra_left
```
Furthermore, it is possible to configure `west build` by 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.

For adding multiple arguments a string can be used:
```sh
west config build.cmake-args -- -DSHIELD=kyra_left
```

```sh
west config build.cmake-args \
-- "-DSHIELD=kyra_left -DZMK_CONFIG=/absolute/path/to/zmk-config"
```
For adding multiple arguments a string can be used:

:::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**.
:::
```sh
west config build.cmake-args \
-- "-DSHIELD=kyra_left -DZMK_CONFIG=/absolute/path/to/zmk-config"
```

</TabItem>
</Tabs>
:::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**.
:::

### Pristine Building

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

Please sign in to comment.