diff --git a/docs/docs/assets/troubleshooting/building/devicetree-step.png b/docs/docs/assets/troubleshooting/building/devicetree-step.png new file mode 100755 index 000000000..f2f75764d Binary files /dev/null and b/docs/docs/assets/troubleshooting/building/devicetree-step.png differ diff --git a/docs/docs/assets/troubleshooting/building/kconfig-step.png b/docs/docs/assets/troubleshooting/building/kconfig-step.png new file mode 100755 index 000000000..34bbdd22f Binary files /dev/null and b/docs/docs/assets/troubleshooting/building/kconfig-step.png differ diff --git a/docs/docs/config/index.md b/docs/docs/config/index.md index 354633a12..d449f4ddf 100644 --- a/docs/docs/config/index.md +++ b/docs/docs/config/index.md @@ -82,6 +82,12 @@ The list of available settings is determined by various files in ZMK whose names See [Zephyr's Kconfig documentation](https://docs.zephyrproject.org/3.5.0/build/kconfig/index.html) for more details on Kconfig files. +:::tip + +You can investigate the [final set of configuration settings](../troubleshooting/building-issues.md#configuration-setting-issues) that are in effect during a build to diagnose any issues with changing Kconfig settings. + +::: + ### KConfig Value Types #### bool @@ -131,6 +137,12 @@ Devicetree properties apply to specific nodes in the tree instead of globally. T See [Zephyr's Devicetree guide](https://docs.zephyrproject.org/3.5.0/build/dts/index.html) for more details on Devicetree files. +:::tip + +You can investigate the [final combined Devicetree](../troubleshooting/building-issues.md#devicetree-related-issues) produced during a build to diagnose any issues with changing Devicetree nodes. + +::: + ### Changing Devicetree Properties Since Devicetree properties are set for specific nodes in the tree, you will first need to find the node you want to configure. You will typically need to diff --git a/docs/docs/troubleshooting/building-issues.md b/docs/docs/troubleshooting/building-issues.md index 24d389abc..13b861b10 100644 --- a/docs/docs/troubleshooting/building-issues.md +++ b/docs/docs/troubleshooting/building-issues.md @@ -60,3 +60,47 @@ Key positions are numbered starting from `0` at the top left key on the keymap, :::tip A common mistake that leads to this error is to use [key press keycodes](keymaps/behaviors/key-press.md) without the leading `&kp` binding. That is, having entries such as `SPACE` that should have been `&kp SPACE`. ::: + +## Diagnosing Unexpected Build Results + +### Configuration Setting Issues + +If you want to ensure that the [configuration settings](../config/index.md#kconfig-files) you intend to change are changed in the build, you can check the final compiled Kconfig file that the firmware build process produces. +This file will display values for all set configurations and includes user, board, shield (if used in build), ZMK, and Zephyr-level settings. + +When using GitHub Actions to build your firmware, the contents of this file are displayed in the "`` Kconfig file" step in your build job: + +![](../assets/troubleshooting/building/kconfig-step.png) + +If you are building locally, this file can be found inside the build folder at `/zephyr/.config`. + +Additionally, the build command (in "West Build (``)" step in GitHub Actions) logs what configuration files were found and used in the build: + +``` ++ west build -s zmk/app -d /tmp/tmp.8cJefinXCb -b corneish_zen_v2_left -- -DZMK_CONFIG=/tmp/zmk-config/config -DZMK_EXTRA_MODULES=/__w/zmk-config/zmk-config +... +-- ZMK Config Kconfig: /tmp/zmk-config/config/corneish_zen.conf +... +``` + +### Devicetree-related Issues + +If you want to ensure that your [devicetree files](../config/index.md#devicetree-files) are processed as you expect, you can check the final compiled devicetree file that the firmware build process produces. +This file will contain a single devicetree that combines all of user, board, and shield (if used in build) devicetree files. +Note that while it will include your keymap contents in it, [keycodes](../keymaps/list-of-keycodes.mdx) like `SPACE` will be displayed instead as hexadecimal numbers like `0x7002a`. + +When using GitHub Actions to build your firmware, the contents of this file are displayed in the "`` Devicetree file" step in your build job: + +![](../assets/troubleshooting/building/devicetree-step.png) + +If you are building locally, this file can be found inside the build folder at `/zephyr/zephyr.dts`. + +Additionally, the build command (in "West Build (``)" step in GitHub Actions) logs what devicetree files were found and used in the build: + +``` ++ west build -s zmk/app -d /tmp/tmp.8cJefinXCb -b corneish_zen_v2_left -- -DZMK_CONFIG=/tmp/zmk-config/config -DZMK_EXTRA_MODULES=/__w/zmk-config/zmk-config +... +-- Found BOARD.dts: /tmp/zmk-config/zmk/app/boards/arm/corneish_zen/corneish_zen_v2_left.dts +-- Found devicetree overlay: /tmp/zmk-config/config/corneish_zen.keymap +... +```