users/drashna/readme_secrets.md

   1 # Secret Macros
   2
   3 With help from gitter and Colinta, this adds the ability to add hidden macros from other users.
   4
   5 First, I have several files that are hidden/excluded from Git/GitHub.  These contain everything needed for the macros. To hide these files, open `.git/info/exclude` and add `secrets.c` and `secrets.h` to that file, below the comments.
   6
   7 And this requires `KC_SECRET_1` through `KC_SECRET_5` to be added in your keycode enum (usually in your `<name>.h` file) the keycodes for the new macros.
   8
   9 ## Git Exclusion
  10
  11 To prevent `git` from seeing, or committing the secret files, you can exclude them.   What's the point of having secrets if they're posted on GitHub for everyone to see!?!
  12
  13 You can do this with the `.git/info/exclude` file, so that it's only ignored locally.  Unfortunately, that means it's not consistently handled on each system.
  14
  15 However, if you create a `.gitignore` file in the same folder, you keep things consistent between every system that the code is checked out on.
  16
  17 ```c
  18 secrets.c
  19 secrets.h
  20 ```
  21
  22 ## secrets.c
  23
  24 Here is the magic. This handles including the "secrets", and adding the custom macros to send them.
  25
  26 ```c
  27 #include "drashna.h"  // replace with your keymap's "h" file, or whatever file stores the keycodes
  28
  29 #if (__has_include("secrets.h") && !defined(NO_SECRETS))
  30 #include "secrets.h"
  31 #else
  32 // `PROGMEM const char secret[][x]` may work better, but it takes up more space in the firmware
  33 // And I'm not familiar enough to know which is better or why...
  34 static const char * const secret[] = {
  35   "test1",
  36   "test2",
  37   "test3",
  38   "test4",
  39   "test5"
  40 };
  41 #endif
  42
  43 bool process_record_secrets(uint16_t keycode, keyrecord_t *record) {
  44   switch (keycode) {
  45     case KC_SECRET_1 ... KC_SECRET_5: // Secrets!  Externally defined strings, not stored in repo
  46       if (!record->event.pressed) {
  47         clear_oneshot_layer_state(ONESHOT_OTHER_KEY_PRESSED);
  48         send_string_with_delay(secret[keycode - KC_SECRET_1], MACRO_TIMER);
  49       }
  50       return false;
  51       break;
  52   }
  53   return true;
  54 }
  55 ```
  56
  57 ## secrets.h
  58
  59 Now, for the actual secrets!  The file needs to look like
  60
  61 ```c
  62 static const char *  secrets[] = {
  63   "secret1",
  64   "secret2",
  65   "secret3",
  66   "secret4",
  67   "secret5"
  68 };
  69 ```
  70
  71 Replacing the strings with the codes that you need.
  72
  73 ## Process Record
  74
  75 In whichever file you have your `process_record_*` function in, you will want to add this to the top:
  76
  77 ```c
  78 __attribute__ ((weak))
  79 bool process_record_secrets(uint16_t keycode, keyrecord_t *record) {
  80   return true;
  81 }
  82 ```
  83
  84 This is so that the function can be called here, and replaced in the `secrets.c` file, and so it won't error out if it doesn't exist.
  85
  86 And then, in the `process_record_user` function, assuming you have `return process_record_keymap(keycode, record)` here,  you'll want to replace the "final" return with the following. Otherwise, you want to replace the `return true;` with `return process_record_secrets(keycode, record);`
  87
  88 ```c
  89 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
  90     // your existing macro code here.
  91     return process_record_keymap(keycode, record) && process_record_secrets(keycode, record);
  92 }
  93 ```
  94
  95 ## rules.mk
  96
  97 Here, you want your `/users/<name>/rules.mk` file to "detect" the existence of the `secrets.c` file, and only add it if the file exists.
  98
  99 Additionally, to ensure that it's not added or processed in any way, it checks to see if `NO_SECRETS` is set. This way, if you run `make keyboard:name NO_SECRETS=yes`, it will remove the feature altogether.
 100
 101 ```make
 102 ifneq ($(strip $(NO_SECRETS)), yes)
 103     ifneq ("$(wildcard $(USER_PATH)/secrets.c)","")
 104         SRC += secrets.c
 105     endif
 106 endif
 107 ```
 108
 109 Alternately, if you want to make sure that you can disable the function without messing with the file, you need to add this to your `/users/<name>/rules.mk`, so that it catches the flag:
 110
 111 ```make
 112 ifneq ("$(wildcard $(USER_PATH)/secrets.c)","")
 113   SRC += secrets.c
 114 endif
 115
 116 ifeq ($(strip $(NO_SECRETS)), yes)
 117     OPT_DEFS += -DNO_SECRETS
 118 endif
 119 ```
 120
 121 ## Extras
 122
 123 Additionally, because this file isn't present in the repo at all, you could add additional functionality that nobody else will see.