Skip to content

Commit

Permalink
docs: Documented the improved local setup for the native approach.
Browse files Browse the repository at this point in the history
  • Loading branch information
Nick-Munnich committed Dec 12, 2024
1 parent 112ee5f commit 18e9c7e
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 17 deletions.
35 changes: 20 additions & 15 deletions docs/docs/development/local-toolchain/build-flash.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,11 @@ Build times can be significantly reduced after the initial build by omitting all

### Building With External Modules

ZMK supports loading additional boards, shields, code, etc. from [external Zephyr modules](https://docs.zephyrproject.org/3.5.0/develop/modules.html), facilitating out-of-tree management and versioning independent of the ZMK repository. To build with any additional modules, use the `ZMK_EXTRA_MODULES` define added to your `west build` command.
ZMK supports loading additional boards, shields, code, etc. from [external Zephyr modules](https://docs.zephyrproject.org/3.5.0/develop/modules.html), facilitating out-of-tree management and versioning independent of the ZMK repository.

**Building with any modules specified in `zmk/zmk-config/config/west.yml` is done automatically.**

To build with any additional modules beyond that, use the `ZMK_EXTRA_MODULES` define added to your `west build` command.

For instance, building with the `my-vendor-keebs-module` checked out to your documents directory, you would build like:

Expand All @@ -157,27 +161,28 @@ When adding multiple modules, make sure they are separated by a semicolon, e.g.:
west build -b nice_nano_v2 -- -DSHIELD=vendor_shield -DZMK_EXTRA_MODULES="C:/Users/myUser/Documents/my-vendor-keebs-module;C:/Users/myUser/Documents/my-other-keebs-module"
```

### Building from `zmk-config` Folder
### Building from Alternative `zmk-config` Folders

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.**
ZMK will build using files from your []`zmk/zmk-config/config` folder](../../user-setup.mdx#github-repo) automatically.
If you have an alternative `zmk-config` that you'd like to use instead, you can point to it with the `ZMK_CONFIG` CMake argument.

For instance, building kyria firmware from a user `myUser`'s `zmk-config` folder
on Windows may look something like this:
Add the `-DZMK_CONFIG="C:/the/absolute/path/alternative/config"` to your `west build`
command. **Notice that this path should point to the folder labeled `config`
within your `zmk-config` folder.** For example:

```sh
west build -b nice_nano -- -DSHIELD=kyria_left \
-DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config/config"
-DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config-two/config"
```

:::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 this alternative config is also a [module](../../features/modules.mdx), you will need to mark it as such with the `ZMK_CONFIG_LOCAL_MODULE` flag.
Note that this flag should point to the `zmk-config` root, _not_ the folder labeled `config`.

```sh
west build -b nice_nano -- -DSHIELD=kyria_left \
-DZMK_CONFIG="C:/Users/myUser/Documents/Github/zmk-config-two/config" \
-DZMK_CONFIG_LOCAL_MODULE="C:/Users/myUser/Documents/Github/zmk-config-two"
```

## Flashing

Expand Down
10 changes: 8 additions & 2 deletions docs/docs/development/local-toolchain/setup/native.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,12 @@ Then step into the repository.
cd zmk
```

Clone your `zmk-config` into the repository, making sure that the local name for it is `zmk-config`.

```sh
git clone [email protected]:<Your Username>/zmk-config.git zmk-config
```

## 3. Get Zephyr and install Python dependencies

:::note
Expand Down Expand Up @@ -179,7 +185,7 @@ pip install west
5. Initialize the application and update to fetch modules, including Zephyr:

```sh
west init -l app/
west init -l local/
west update
```

Expand Down Expand Up @@ -268,7 +274,7 @@ pip3 install -U west
2. Initialize the application and update to fetch modules, including Zephyr:

```sh
west init -l app/
west init -l local/
west update
```

Expand Down

0 comments on commit 18e9c7e

Please sign in to comment.