Creates a userspace for keymaps (qmk#1559)

* create a user space * adds example * document, add readme.md * jackhumbert userspace, ergodox keymap
mrkn · Oct 21, 2017 · 06f196c · 06f196c
1 parent 9bb259b
commit 06f196c
Show file tree

Hide file tree

Showing 14 changed files with 92 additions and 0 deletions.
diff --git a/build_keyboard.mk b/build_keyboard.mk
@@ -183,6 +183,10 @@ else
     # this state should never be reached
 endif
 
+# User space stuff
+USER_PATH := users/$(KEYMAP)
+-include $(USER_PATH)/rules.mk
+
 # Object files directory
 #     To put object files in current directory, use a dot (.), do NOT make
 #     this an empty or blank macro!
@@ -204,6 +208,7 @@ SRC += $(KEYBOARD_SRC) \
 VPATH += $(KEYMAP_PATH)
 VPATH += $(KEYBOARD_PATHS)
 VPATH += $(COMMON_VPATH)
+VPATH += $(USER_PATH)
 
 include common_features.mk
 include $(TMK_PATH)/protocol.mk

diff --git a/docs/_summary.md b/docs/_summary.md
@@ -15,6 +15,7 @@
 * [Features](features.md)
   * [Layouts](feature_layouts.md)
   * [Common Shortcuts](feature_common_shortcuts.md)
+  * [Userspace](feature_userspace.md)
   * [Backlight](feature_backlight.md)
   * [Bootmagic](feature_bootmagic.md)
   * [Dynamic Macros](dynamic_macros.md)

diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md
@@ -0,0 +1,33 @@
+# Userspace: sharing code between keymaps
+
+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:
+
+* `/users/<name>/` (added to the path automatically)
+  * `readme.md`
+  * `rules.mk` (included automatically)
+  * `<name>.h` (optional)
+  * `<name>.c` (optional)
+
+`<name>.c` will need to be added to the SRC in `rules.mk` like this:
+
+    SRC += <name>.c
+
+Additional files may be added in the same way - it's recommended you have one named `<name>`.c/.h though.
+
+All this only happens when you build a keymap named `<name>`, like this:
+
+    make planck:<name>
+
+For example, 
+
+    make planck:jack
+
+Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.
+
+## Readme
+
+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).
+
+## Example
+
+For a brief example, checkout `/users/_example/` until we have more reasonable and useful examples.
diff --git a/layouts/community/ergodox/jack/config.h → ...ts/community/ergodox/jackhumbert/config.h b/layouts/community/ergodox/jack/config.h → ...ts/community/ergodox/jackhumbert/config.h
diff --git a/layouts/community/ergodox/jack/keymap.c → ...ts/community/ergodox/jackhumbert/keymap.c b/layouts/community/ergodox/jack/keymap.c → ...ts/community/ergodox/jackhumbert/keymap.c
diff --git a/users/_example/_example.c b/users/_example/_example.c
@@ -0,0 +1,5 @@
+#include "_example.h"
+
+void my_custom_function(void) {
+
+}
diff --git a/users/_example/_example.h b/users/_example/_example.h
@@ -0,0 +1,8 @@
+#ifndef USERSPACE
+#define USERSPACE
+
+#include "quantum.h"
+
+void my_custom_function(void);
+
+#endif
diff --git a/users/_example/readme.md b/users/_example/readme.md
@@ -0,0 +1,14 @@
+Copyright <year> <name> <email> @<github_username>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
diff --git a/users/_example/rules.mk b/users/_example/rules.mk
@@ -0,0 +1 @@
+SRC += _example.c
diff --git a/users/jackhumbert/jackhumbert.c b/users/jackhumbert/jackhumbert.c
@@ -0,0 +1 @@
+#include "jackhumbert.h"
diff --git a/users/jackhumbert/jackhumbert.h b/users/jackhumbert/jackhumbert.h
@@ -0,0 +1,6 @@
+#ifndef USERSPACE
+#define USERSPACE
+
+#include "quantum.h"
+
+#endif
diff --git a/users/jackhumbert/readme.md b/users/jackhumbert/readme.md
@@ -0,0 +1,14 @@
+Copyright 2017 Jack Humbert <jack.humb@gmail.com> @jackhumbert
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
diff --git a/users/jackhumbert/rules.mk b/users/jackhumbert/rules.mk
@@ -0,0 +1 @@
+SRC += jackhumbert.c
diff --git a/users/readme.md b/users/readme.md
@@ -0,0 +1,3 @@
+# User space
+
+This is a place for users to put code that they might use between keyboards. If you build the keymap `mine`, `/users/mine/rules.mk` will be included in your build, and `/users/mine/` will be in your path - keep these things in mind when naming your files and referencing them from other places.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# User space

		This is a place for users to put code that they might use between keyboards. If you build the keymap `mine`, `/users/mine/rules.mk` will be included in your build, and `/users/mine/` will be in your path - keep these things in mind when naming your files and referencing them from other places.