summaryrefslogtreecommitdiff
path: root/docs/config_options.md
diff options
context:
space:
mode:
authorNick Brassel <nick@tzarc.org>2024-05-30 12:00:41 +1000
committerGitHub <noreply@github.com>2024-05-30 12:00:41 +1000
commit6ef97172889ccd5db376b2a9f8825489e24fdac4 (patch)
tree334e3bf41c8554d4bee73a140822f95f60eb64e9 /docs/config_options.md
parent395766657ff98a4b1fd0dcba5917557f8acbb9e4 (diff)
Vitepress conversion of docs. (#23795)
Diffstat (limited to 'docs/config_options.md')
-rw-r--r--docs/config_options.md38
1 files changed, 20 insertions, 18 deletions
diff --git a/docs/config_options.md b/docs/config_options.md
index 046429a587..236649a0ea 100644
--- a/docs/config_options.md
+++ b/docs/config_options.md
@@ -6,11 +6,13 @@ There are three main types of configuration files in QMK:
6 6
7* `config.h`, which contains various preprocessor directives (`#define`, `#ifdef`) 7* `config.h`, which contains various preprocessor directives (`#define`, `#ifdef`)
8* `rules.mk`, which contains additional variables 8* `rules.mk`, which contains additional variables
9* `info.json`, which is utilized for [data-driven configuration](https://docs.qmk.fm/#/data_driven_config) 9* `info.json`, which is utilized for [data-driven configuration](data_driven_config)
10 10
11This page will only discuss the first two types, `config.h` and `rules.mk`. 11This page will only discuss the first two types, `config.h` and `rules.mk`.
12 12
13?> While not all settings have data-driven equivalents yet, keyboard makers are encouraged to utilize the `info.json` file to set the metadata for their boards when possible. See the [`info.json` Format](https://docs.qmk.fm/#/reference_info_json) page for more details. 13::: tip
14While not all settings have data-driven equivalents yet, keyboard makers are encouraged to utilize the `info.json` file to set the metadata for their boards when possible. See the [`info.json` Format](reference_info_json) page for more details.
15:::
14 16
15These files exist at various levels in QMK and all files of the same type are combined to build the final configuration. The levels, from lowest priority to highest priority, are: 17These files exist at various levels in QMK and all files of the same type are combined to build the final configuration. The levels, from lowest priority to highest priority, are:
16 18
@@ -56,10 +58,10 @@ This is a C header file that is one of the first things included, and will persi
56 * the number of columns in your keyboard's matrix 58 * the number of columns in your keyboard's matrix
57* `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }` 59* `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }`
58 * pins of the rows, from top to bottom 60 * pins of the rows, from top to bottom
59 * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. 61 * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions#low-level-matrix-overrides) for more information.
60* `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }` 62* `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
61 * pins of the columns, from left to right 63 * pins of the columns, from left to right
62 * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. 64 * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions#low-level-matrix-overrides) for more information.
63* `#define MATRIX_IO_DELAY 30` 65* `#define MATRIX_IO_DELAY 30`
64 * the delay in microseconds when between changing matrix pin state and reading values 66 * the delay in microseconds when between changing matrix pin state and reading values
65* `#define MATRIX_HAS_GHOST` 67* `#define MATRIX_HAS_GHOST`
@@ -151,26 +153,26 @@ If you define these options you will enable the associated feature, which may in
151 * enables handling for per key `TAPPING_TERM` settings 153 * enables handling for per key `TAPPING_TERM` settings
152* `#define RETRO_TAPPING` 154* `#define RETRO_TAPPING`
153 * tap anyway, even after `TAPPING_TERM`, if there was no other key interruption between press and release 155 * tap anyway, even after `TAPPING_TERM`, if there was no other key interruption between press and release
154 * See [Retro Tapping](tap_hold.md#retro-tapping) for details 156 * See [Retro Tapping](tap_hold#retro-tapping) for details
155* `#define RETRO_TAPPING_PER_KEY` 157* `#define RETRO_TAPPING_PER_KEY`
156 * enables handling for per key `RETRO_TAPPING` settings 158 * enables handling for per key `RETRO_TAPPING` settings
157* `#define TAPPING_TOGGLE 2` 159* `#define TAPPING_TOGGLE 2`
158 * how many taps before triggering the toggle 160 * how many taps before triggering the toggle
159* `#define PERMISSIVE_HOLD` 161* `#define PERMISSIVE_HOLD`
160 * makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM` 162 * makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM`
161 * See [Permissive Hold](tap_hold.md#permissive-hold) for details 163 * See [Permissive Hold](tap_hold#permissive-hold) for details
162* `#define PERMISSIVE_HOLD_PER_KEY` 164* `#define PERMISSIVE_HOLD_PER_KEY`
163 * enabled handling for per key `PERMISSIVE_HOLD` settings 165 * enabled handling for per key `PERMISSIVE_HOLD` settings
164* `#define QUICK_TAP_TERM 100` 166* `#define QUICK_TAP_TERM 100`
165 * tap-then-hold timing to use a dual role key to repeat keycode 167 * tap-then-hold timing to use a dual role key to repeat keycode
166 * See [Quick Tap Term](tap_hold.md#quick-tap-term) 168 * See [Quick Tap Term](tap_hold#quick-tap-term)
167 * Changes the timing of Tap Toggle functionality (`TT` or the One Shot Tap Toggle) 169 * Changes the timing of Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
168 * Defaults to `TAPPING_TERM` if not defined 170 * Defaults to `TAPPING_TERM` if not defined
169* `#define QUICK_TAP_TERM_PER_KEY` 171* `#define QUICK_TAP_TERM_PER_KEY`
170 * enables handling for per key `QUICK_TAP_TERM` settings 172 * enables handling for per key `QUICK_TAP_TERM` settings
171* `#define HOLD_ON_OTHER_KEY_PRESS` 173* `#define HOLD_ON_OTHER_KEY_PRESS`
172 * selects the hold action of a dual-role key as soon as the tap of the dual-role key is interrupted by the press of another key. 174 * selects the hold action of a dual-role key as soon as the tap of the dual-role key is interrupted by the press of another key.
173 * See "[hold on other key press](tap_hold.md#hold-on-other-key-press)" for details 175 * See "[hold on other key press](tap_hold#hold-on-other-key-press)" for details
174* `#define HOLD_ON_OTHER_KEY_PRESS_PER_KEY` 176* `#define HOLD_ON_OTHER_KEY_PRESS_PER_KEY`
175 * enables handling for per key `HOLD_ON_OTHER_KEY_PRESS` settings 177 * enables handling for per key `HOLD_ON_OTHER_KEY_PRESS` settings
176* `#define LEADER_TIMEOUT 300` 178* `#define LEADER_TIMEOUT 300`
@@ -205,7 +207,7 @@ If you define these options you will enable the associated feature, which may in
205* `#define TAP_HOLD_CAPS_DELAY 80` 207* `#define TAP_HOLD_CAPS_DELAY 80`
206 * Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPS_LOCK` keycode, as this has some special handling on MacOS. The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher. 208 * Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPS_LOCK` keycode, as this has some special handling on MacOS. The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher.
207* `#define KEY_OVERRIDE_REPEAT_DELAY 500` 209* `#define KEY_OVERRIDE_REPEAT_DELAY 500`
208 * Sets the key repeat interval for [key overrides](feature_key_overrides.md). 210 * Sets the key repeat interval for [key overrides](feature_key_overrides).
209* `#define LEGACY_MAGIC_HANDLING` 211* `#define LEGACY_MAGIC_HANDLING`
210 * Enables magic configuration handling for advanced keycodes (such as Mod Tap and Layer Tap) 212 * Enables magic configuration handling for advanced keycodes (such as Mod Tap and Layer Tap)
211 213
@@ -215,14 +217,14 @@ If you define these options you will enable the associated feature, which may in
215* `#define WS2812_DI_PIN D7` 217* `#define WS2812_DI_PIN D7`
216 * pin the DI on the WS2812 is hooked-up to 218 * pin the DI on the WS2812 is hooked-up to
217* `#define RGBLIGHT_LAYERS` 219* `#define RGBLIGHT_LAYERS`
218 * Lets you define [lighting layers](feature_rgblight.md?id=lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state. 220 * Lets you define [lighting layers](feature_rgblight#lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state.
219* `#define RGBLIGHT_MAX_LAYERS` 221* `#define RGBLIGHT_MAX_LAYERS`
220 * Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight.md?id=lighting-layers) are needed. 222 * Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight#lighting-layers) are needed.
221 * Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards. 223 * Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards.
222* `#define RGBLIGHT_LAYER_BLINK` 224* `#define RGBLIGHT_LAYER_BLINK`
223 * Adds ability to [blink](feature_rgblight.md?id=lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action). 225 * Adds ability to [blink](feature_rgblight#lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action).
224* `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` 226* `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF`
225 * If defined, then [lighting layers](feature_rgblight?id=overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off. 227 * If defined, then [lighting layers](feature_rgblight#overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off.
226* `#define RGBLIGHT_LED_COUNT 12` 228* `#define RGBLIGHT_LED_COUNT 12`
227 * number of LEDs 229 * number of LEDs
228* `#define RGBLIGHT_SPLIT` 230* `#define RGBLIGHT_SPLIT`
@@ -294,7 +296,7 @@ There are a few different ways to set handedness for split keyboards (listed in
294* `#define MATRIX_ROW_PINS_RIGHT { <row pins> }` 296* `#define MATRIX_ROW_PINS_RIGHT { <row pins> }`
295* `#define MATRIX_COL_PINS_RIGHT { <col pins> }` 297* `#define MATRIX_COL_PINS_RIGHT { <col pins> }`
296 * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns. 298 * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns.
297 * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. 299 * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions#low-level-matrix-overrides) for more information.
298 300
299* `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }` 301* `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
300 * If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`. 302 * If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`.
@@ -356,7 +358,7 @@ There are a few different ways to set handedness for split keyboards (listed in
356 358
357* `#define SPLIT_TRANSACTION_IDS_KB .....` 359* `#define SPLIT_TRANSACTION_IDS_KB .....`
358* `#define SPLIT_TRANSACTION_IDS_USER .....` 360* `#define SPLIT_TRANSACTION_IDS_USER .....`
359 * Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](feature_split_keyboard.md#custom-data-sync) for more information. 361 * Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](feature_split_keyboard#custom-data-sync) for more information.
360 362
361# The `rules.mk` File 363# The `rules.mk` File
362 364
@@ -385,7 +387,7 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
385 ... a.o c.o ... lib_b.a lib_d.a ... 387 ... a.o c.o ... lib_b.a lib_d.a ...
386 ``` 388 ```
387* `LAYOUTS` 389* `LAYOUTS`
388 * A list of [layouts](feature_layouts.md) this keyboard supports. 390 * A list of [layouts](feature_layouts) this keyboard supports.
389* `LTO_ENABLE` 391* `LTO_ENABLE`
390 * Enables Link Time Optimization (LTO) when compiling the keyboard. This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable). 392 * Enables Link Time Optimization (LTO) when compiling the keyboard. This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).
391 393
@@ -404,7 +406,7 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
404 * `bootloadhid` 406 * `bootloadhid`
405 * `usbasploader` 407 * `usbasploader`
406 408
407## Feature Options :id=feature-options 409## Feature Options {#feature-options}
408 410
409Use these to enable or disable building certain features. The more you have enabled the bigger your firmware will be, and you run the risk of building a firmware too large for your MCU. 411Use these to enable or disable building certain features. The more you have enabled the bigger your firmware will be, and you run the risk of building a firmware too large for your MCU.
410 412
@@ -451,7 +453,7 @@ Use these to enable or disable building certain features. The more you have enab
451* `NO_USB_STARTUP_CHECK` 453* `NO_USB_STARTUP_CHECK`
452 * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master. 454 * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master.
453* `DEFERRED_EXEC_ENABLE` 455* `DEFERRED_EXEC_ENABLE`
454 * Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions.md#deferred-execution) for more information. 456 * Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions#deferred-execution) for more information.
455* `DYNAMIC_TAPPING_TERM_ENABLE` 457* `DYNAMIC_TAPPING_TERM_ENABLE`
456 * Allows to configure the global tapping term on the fly. 458 * Allows to configure the global tapping term on the fly.
457 459