aboutsummaryrefslogtreecommitdiffstats
path: root/docs/feature_userspace.md
diff options
context:
space:
mode:
authorFrançois Magimel2025-09-09 23:51:13 +0200
committerGitHub2025-09-09 23:51:13 +0200
commit09ab67c0440d8e5e3faf832d23eb1b754845a573 (patch)
tree0edccafc937149afdc8b964004f61fe80942cfa2 /docs/feature_userspace.md
parent7be4540b4688eab74920eb4cb2347af43fb6a779 (diff)
docs: fix misspellings (#25555)
* docs: fix misspellings * docs: do line breaks with HTML instead of spaces To remove trailing spaces and to avoid breaking things, line breaks can be done with the HTML br tag.
Diffstat (limited to 'docs/feature_userspace.md')
-rw-r--r--docs/feature_userspace.md43
1 files changed, 22 insertions, 21 deletions
diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md
index 0f5c4a5f96..2c8c08b38e 100644
--- a/docs/feature_userspace.md
+++ b/docs/feature_userspace.md
@@ -24,10 +24,10 @@ For example,
make planck:jack
-Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.
+Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.
::: warning
-This `name` can be [overridden](#override-default-userspace), if needed.
+This `name` can be [overridden](#override-default-userspace), if needed.
:::
## `Rules.mk`
@@ -38,9 +38,9 @@ It's highly recommended that you use `<name>.c` as the default source file to be
SRC += <name>.c
-Additional files may be added in the same way - it's recommended you have one named `<name>`.c/.h to start off with, though.
+Additional files may be added in the same way - it's recommended you have one named `<name>`.c/.h to start off with, though.
-The `/users/<name>/rules.mk` file will be included in the build _after_ the `rules.mk` from your keymap. This allows you to have features in your userspace `rules.mk` that depend on individual QMK features that may or may not be available on a specific keyboard.
+The `/users/<name>/rules.mk` file will be included in the build _after_ the `rules.mk` from your keymap. This allows you to have features in your userspace `rules.mk` that depend on individual QMK features that may or may not be available on a specific keyboard.
For example, if you have RGB control features shared between all your keyboards that support RGB lighting, you can add support for that if the RGBLIGHT feature is enabled:
```make
@@ -82,7 +82,7 @@ You should use the `config.h` for [configuration options](config_options), and t
Please include authorship (your name, GitHub username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses).
-You can use this as a template:
+You can use this as a template:
```
Copyright <year> <name> <email> @<github_username>
@@ -100,9 +100,9 @@ You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
```
-You'd want to replace the year, name, email and GitHub username with your info.
+You'd want to replace the year, name, email and GitHub username with your info.
-Additionally, this is a good place to document your code, if you wish to share it with others.
+Additionally, this is a good place to document your code, if you wish to share it with others.
## Build All Keyboards That Support a Specific Keymap
@@ -118,20 +118,21 @@ This is ideal for when you want ensure everything compiles successfully when pre
## Examples
-For a brief example, checkout [`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/_example).
-For more complicated examples, checkout the [`awesome-qmk` colletion](https://github.com/qmk/awesome-qmk).
+For a brief example, checkout [`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/_example).
+
+For more complicated examples, checkout the [`awesome-qmk` collection](https://github.com/qmk/awesome-qmk).
### Customized Functions
-QMK has a bunch of [functions](custom_quantum_functions) that have [`_quantum`, `_kb`, and `_user` versions](custom_quantum_functions#a-word-on-core-vs-keyboards-vs-keymap) that you can use. You will pretty much always want to use the user version of these functions. But the problem is that if you use them in your userspace, then you don't have a version that you can use in your keymap.
+QMK has a bunch of [functions](custom_quantum_functions) that have [`_quantum`, `_kb`, and `_user` versions](custom_quantum_functions#a-word-on-core-vs-keyboards-vs-keymap) that you can use. You will pretty much always want to use the user version of these functions. But the problem is that if you use them in your userspace, then you don't have a version that you can use in your keymap.
-However, you can actually add support for keymap version, so that you can use it in both your userspace and your keymap!
+However, you can actually add support for keymap version, so that you can use it in both your userspace and your keymap!
-For instance, let's look at the `layer_state_set_user()` function. You can enable the [Tri Layer State](ref_functions#olkb-tri-layers) functionality on all of your boards, while also retaining the Tri Layer functionality in your `keymap.c` files.
+For instance, let's look at the `layer_state_set_user()` function. You can enable the [Tri Layer State](ref_functions#olkb-tri-layers) functionality on all of your boards, while also retaining the Tri Layer functionality in your `keymap.c` files.
-In your `<name.c>` file, you'd want to add this:
+In your `<name.c>` file, you'd want to add this:
```c
__attribute__ ((weak))
layer_state_t layer_state_set_keymap (layer_state_t state) {
@@ -143,7 +144,7 @@ layer_state_t layer_state_set_user (layer_state_t state) {
return layer_state_set_keymap (state);
}
```
-The `__attribute__ ((weak))` part tells the compiler that this is a placeholder function that can then be replaced by a version in your `keymap.c`. That way, you don't need to add it to your `keymap.c`, but if you do, you won't get any conflicts because the function is the same name.
+The `__attribute__ ((weak))` part tells the compiler that this is a placeholder function that can then be replaced by a version in your `keymap.c`. That way, you don't need to add it to your `keymap.c`, but if you do, you won't get any conflicts because the function is the same name.
The `_keymap` part here doesn't matter, it just needs to be something other than `_quantum`, `_kb`, or `_user`, since those are already in use. So you could use `layer_state_set_mine`, `layer_state_set_fn`, or anything else.
@@ -151,7 +152,7 @@ You can see a list of this and other common functions in [`template.c`](https://
### Custom Features
-Since the Userspace feature can support a staggering number of boards, you may have boards that you want to enable certain functionality for, but not for others. And you can actually create "features" that you can enable or disable in your own userspace.
+Since the Userspace feature can support a staggering number of boards, you may have boards that you want to enable certain functionality for, but not for others. And you can actually create "features" that you can enable or disable in your own userspace.
For instance, if you wanted to have a bunch of macros available, but only on certain boards (to save space), you could "hide" them being a `#ifdef MACROS_ENABLED`, and then enable it per board. To do this, add this to your rules.mk
```make
@@ -159,11 +160,11 @@ ifeq ($(strip $(MACROS_ENABLED)), yes)
OPT_DEFS += -DMACROS_ENABLED
endif
```
-The `OPT_DEFS` setting causes `MACROS_ENABLED` to be defined for your keyboards (note the `-D` in front of the name), and you could use `#ifdef MACROS_ENABLED` to check the status in your c/h files, and handle that code based on that.
+The `OPT_DEFS` setting causes `MACROS_ENABLED` to be defined for your keyboards (note the `-D` in front of the name), and you could use `#ifdef MACROS_ENABLED` to check the status in your c/h files, and handle that code based on that.
Then you add `MACROS_ENABLED = yes` to the `rules.mk` for you keymap to enable this feature and the code in your userspace.
-And in your `process_record_user` function, you'd do something like this:
+And in your `process_record_user` function, you'd do something like this:
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
@@ -187,9 +188,9 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
### Consolidated Macros
-If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that. This builds upon the [Customized Functions](#customized-functions) example above. This lets you maintain a bunch of macros that are shared between the different keyboards, and allow for keyboard specific macros, too.
+If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that. This builds upon the [Customized Functions](#customized-functions) example above. This lets you maintain a bunch of macros that are shared between the different keyboards, and allow for keyboard specific macros, too.
-First, you'd want to go through all of your `keymap.c` files and replace `process_record_user` with `process_record_keymap` instead. This way, you can still use keyboard specific codes on those boards, and use your custom "global" keycodes as well. You'll also want to replace `SAFE_RANGE` with `NEW_SAFE_RANGE` so that you wont have any overlapping keycodes
+First, you'd want to go through all of your `keymap.c` files and replace `process_record_user` with `process_record_keymap` instead. This way, you can still use keyboard specific codes on those boards, and use your custom "global" keycodes as well. You'll also want to replace `SAFE_RANGE` with `NEW_SAFE_RANGE` so that you won't have any overlapping keycodes
Then add `#include "<name>.h"` to all of your keymap.c files. This allows you to use these new keycodes without having to redefine them in each keymap.
@@ -245,7 +246,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
}
```
-For boards that may not have a shift button (such as on a macro pad), we need a way to always include the bootloader option. To do that, add the following to the `rules.mk` in your userspace folder:
+For boards that may not have a shift button (such as on a macro pad), we need a way to always include the bootloader option. To do that, add the following to the `rules.mk` in your userspace folder:
```make
ifeq ($(strip $(FLASH_BOOTLOADER)), yes)
@@ -255,7 +256,7 @@ endif
This will add a new `KC_MAKE` keycode that can be used in any of your keymaps. And this keycode will output `make <keyboard>:<keymap>`, making frequent compiling easier. And this will work with any keyboard and any keymap as it will output the current boards info, so that you don't have to type this out every time.
-Also, holding Shift will add the flash target (`:flash`) to the command. Holding Control will add some commands that will speed up compiling time by processing multiple files at once.
+Also, holding Shift will add the flash target (`:flash`) to the command. Holding Control will add some commands that will speed up compiling time by processing multiple files at once.
And for the boards that lack a shift key, or that you want to always attempt the flashing part, you can add `FLASH_BOOTLOADER = yes` to the `rules.mk` of that keymap.