docs/feature_userspace.md

   1 # Userspace: Sharing Code Between Keymaps
   2
   3 If you use more than one keyboard with a similar keymap, you might see the benefit in being able to share code between them. Create your own folder in `users/` named the same as your keymap (ideally your github username, `<name>`) with the following structure:
   4
   5 * `/users/<name>/` (added to the path automatically)
   6   * `readme.md`
   7   * `rules.mk` (included automatically)
   8   * `<name>.h` (optional)
   9   * `<name>.c` (optional)
  10
  11 `<name>.c` will need to be added to the SRC in `rules.mk` like this:
  12
  13     SRC += <name>.c
  14
  15 Additional files may be added in the same way - it's recommended you have one named `<name>`.c/.h though.
  16
  17 All this only happens when you build a keymap named `<name>`, like this:
  18
  19     make planck:<name>
  20
  21 For example,
  22
  23     make planck:jack
  24
  25 Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.
  26
  27 ## Readme
  28
  29 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).
  30
  31 ## Example
  32
  33 For a brief example, checkout `/users/_example/` , or for a more detailed examples check out [`template.h`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.h) and [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) in `/users/drashna/` .
  34
  35 ### Consolidated Macros
  36
  37 If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that.  The issue is that you then cannot call any function defined in your userspace, or it gets complicated.  To better handle this, you can call the functions here and create new functions to use in individual keymaps.
  38
  39 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
  40
  41 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.
  42
  43 Once you've done that, you'll want to set the keycode definitions that you need to the `<name>.h`  file. For instance:
  44 ```
  45 #ifndef USERSPACE
  46 #define USERSPACE
  47
  48 #include "quantum.h"
  49
  50 // Define all of
  51 enum custom_keycodes {
  52   KC_MAKE = SAFE_RANGE,
  53   NEW_SAFE_RANGE  //use "NEW_SAFE_RANGE" for keymap specific codes
  54 };
  55
  56 #endif
  57 ```
  58
  59 Now you want to create the `<name>.c` file, and add this content to it:
  60
  61 ```
  62 #include "<name>.h"
  63 #include "quantum.h"
  64 #include "action.h"
  65 #include "version.h"
  66
  67 __attribute__ ((weak))
  68 bool process_record_keymap(uint16_t keycode, keyrecord_t *record) {
  69   return true;
  70 }
  71
  72 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
  73   switch (keycode) {
  74   case KC_MAKE:
  75     if (!record->event.pressed) {
  76       SEND_STRING("make " QMK_KEYBOARD ":" QMK_KEYMAP
  77 #if  (defined(BOOTLOADER_DFU) || defined(BOOTLOADER_LUFA_DFU) || defined(BOOTLOADER_QMK_DFU))
  78        ":dfu "
  79 #elif defined(BOOTLOADER_HALFKAY)
  80       ":teensy "
  81 #elif defined(BOOTLOADER_CATERINA)
  82        ":avrdude "
  83 #endif
  84         SS_TAP(X_ENTER));
  85     }
  86     return false;
  87     break;
  88   }
  89   return process_record_keymap(keycode, record);
  90 }
  91 ```
  92
  93 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.
  94
  95 Additionally, this should flash the newly compiled firmware automatically, using the correct utility, based on the bootloader settings (or default to just generating the HEX file). However, it should be noted that this may not work on all systems. AVRDUDE doesn't work on WSL, namely (and will dump the HEX in the ".build" folder instead).