diff --git a/docs/docs/development/build-flash.mdx b/docs/docs/development/build-flash.mdx index 20e9e20a..cfcb39ee 100644 --- a/docs/docs/development/build-flash.mdx +++ b/docs/docs/development/build-flash.mdx @@ -108,6 +108,10 @@ west build -b nice_nano -- -DSHIELD=kyria_left -DZMK_CONFIG="C:/Users/myUser/Doc 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. ::: +:::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: diff --git a/docs/docs/development/new-shield.mdx b/docs/docs/development/new-shield.mdx index bcf9b62f..ae97f6af 100644 --- a/docs/docs/development/new-shield.mdx +++ b/docs/docs/development/new-shield.mdx @@ -56,7 +56,7 @@ The repository is a combination of the directories and files required of a ZMK c - The `boards/shields` directory, where the keyboard's files will go - The `zephyr/module.yml` file, which identifies and describes the module. See the [Zephyr documentation](https://docs.zephyrproject.org/3.5.0/develop/modules.html#module-yaml-file-description) for details on customising this file. For the purposes of creating a shield module, the default found in the template can be left untouched. -Neither of these should be moved out of their parent directory. The other files and directories are unnecessary for the purposes of a shield module. +Neither of these should be moved out of their parent directory. The other files and directories such as `config` are not necessary for the purposes of a shield module, but rather intended to be used for user configuration and testing. ## New Shield Directory diff --git a/docs/docs/features/modules.mdx b/docs/docs/features/modules.mdx index 1afc5699..449264e6 100644 --- a/docs/docs/features/modules.mdx +++ b/docs/docs/features/modules.mdx @@ -23,7 +23,9 @@ The shift to using modules for keyboards is a relatively recent one, and not all ## Building With Modules -Adding modules to your ZMK build is as simple as modifying the `west.yml` found in your `zmk-config`'s `config` directory. The recommended way of doing so is: +### GitHub Actions + +When [using GitHub Actions to build ZMK](../user-setup.mdx), adding modules is as simple as modifying the `west.yml` found in your `zmk-config`'s `config` directory. The recommended way of doing so is: 1. Find the URL base (the parent URL) for the module and add it as an entry to the [remotes](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html#remotes). 2. Add the module as an entry to the [projects](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html#projects). @@ -31,7 +33,7 @@ Adding modules to your ZMK build is as simple as modifying the `west.yml` found For more information on `west.yml`, see [West Manifests](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html). -### Examples +#### Examples +### Building Locally + +To add a module to your build when building locally, you will need to clone/copy said module into your local file tree. You can then build using the module as described in ["Building with External Modules"](../development/build-flash.mdx#building-with-external-modules). + ## Beta Testing You may find that there are some features which you desire for which there is a [Pull Request](https://github.com/zmkfirmware/zmk/pulls), but no module. If this is the case, you can still make use of the feature. @@ -131,9 +137,11 @@ branch and create the pull request. ![Repository URL](../assets/features/beta-testing/repo-branch.png) -### Testing Features +## Testing Features -Once you have obtained the correct URL, modify the `west.yml` file simiarly to [Building With Modules](#building-with-modules). Add the remote for the branch like in said section. The difference is that you will need to change the selected remote and revision (or branch) for the `zmk` project. +### GitHub Actions + +When [using GitHub Actions to build ZMK](../user-setup.mdx), once you have obtained the correct URL, you'll need to modify the `west.yml` file simiarly to [Building With Modules](#building-with-modules). Add the remote for the branch like in said section. The difference is that you will need to change the selected remote and revision (or branch) for the `zmk` project. #### Example @@ -180,3 +188,7 @@ manifest: + +### Building Locally + +When building from a pull request locally, you'll need to [perform the local user setup](../development/setup/index.md), but using the repository of the pull request rather than the official ZMK repository. You can then [build and flash](../development/build-flash.mdx) as usual. \ No newline at end of file