Creates a userspace for keymaps (#1559)

* create a user space

* adds example

* document, add readme.md

* jackhumbert userspace, ergodox keymap

14 files changed, 92 insertions, 0 deletions

diff --git a/build_keyboard.mk b/build_keyboard.mk
index 4502078502..2c86fe55ef 100644
--- 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
index edbf04c1a4..55cfd2ab3d 100644
--- 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
new file mode 100644
index 0000000000..edc9f6e32e
--- /dev/null
+++ 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.
\ No newline at end of file
diff --git a/layouts/community/ergodox/jack/config.h b/layouts/community/ergodox/jackhumbert/config.h
index 04bbed611a..04bbed611a 100644
--- a/layouts/community/ergodox/jack/config.h
+++ b/layouts/community/ergodox/jackhumbert/config.h
diff --git a/layouts/community/ergodox/jack/keymap.c b/layouts/community/ergodox/jackhumbert/keymap.c
index 6a00ffa293..6a00ffa293 100644
--- a/layouts/community/ergodox/jack/keymap.c
+++ b/layouts/community/ergodox/jackhumbert/keymap.c
diff --git a/users/_example/_example.c b/users/_example/_example.c
new file mode 100644
index 0000000000..8e0778b122
--- /dev/null
+++ b/users/_example/_example.c
@@ -0,0 +1,5 @@
+#include "_example.h"
+
+void my_custom_function(void) {
+    
+}
\ No newline at end of file
diff --git a/users/_example/_example.h b/users/_example/_example.h
new file mode 100644
index 0000000000..f7c7990257
--- /dev/null
+++ b/users/_example/_example.h
@@ -0,0 +1,8 @@
+#ifndef USERSPACE
+#define USERSPACE
+
+#include "quantum.h"
+
+void my_custom_function(void);
+
+#endif
\ No newline at end of file
diff --git a/users/_example/readme.md b/users/_example/readme.md
new file mode 100644
index 0000000000..fdea33b67a
--- /dev/null
+++ 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/>.
\ No newline at end of file
diff --git a/users/_example/rules.mk b/users/_example/rules.mk
new file mode 100644
index 0000000000..250adc3d0d
--- /dev/null
+++ b/users/_example/rules.mk
@@ -0,0 +1 @@
+SRC += _example.c
\ No newline at end of file
diff --git a/users/jackhumbert/jackhumbert.c b/users/jackhumbert/jackhumbert.c
new file mode 100644
index 0000000000..011e0efb8f
--- /dev/null
+++ b/users/jackhumbert/jackhumbert.c
@@ -0,0 +1 @@
+#include "jackhumbert.h"
\ No newline at end of file
diff --git a/users/jackhumbert/jackhumbert.h b/users/jackhumbert/jackhumbert.h
new file mode 100644
index 0000000000..69cfa67451
--- /dev/null
+++ b/users/jackhumbert/jackhumbert.h
@@ -0,0 +1,6 @@
+#ifndef USERSPACE
+#define USERSPACE
+
+#include "quantum.h"
+
+#endif
\ No newline at end of file
diff --git a/users/jackhumbert/readme.md b/users/jackhumbert/readme.md
new file mode 100644
index 0000000000..479a64140a
--- /dev/null
+++ 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/>.
\ No newline at end of file
diff --git a/users/jackhumbert/rules.mk b/users/jackhumbert/rules.mk
new file mode 100644
index 0000000000..f2981bb786
--- /dev/null
+++ b/users/jackhumbert/rules.mk
@@ -0,0 +1 @@
+SRC += jackhumbert.c
\ No newline at end of file
diff --git a/users/readme.md b/users/readme.md
new file mode 100644
index 0000000000..d8f14d8beb
--- /dev/null
+++ 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.
\ No newline at end of file