Creates a userspace for keymaps (qmk#1559)

* create a user space

* adds example

* document, add readme.md

* jackhumbert userspace, ergodox keymap

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

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)

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.

users/_example/_example.c

@@ -0,0 +1,5 @@
+#include "_example.h"
+
+void my_custom_function(void) {
+
+}

users/_example/_example.h

@@ -0,0 +1,8 @@
+#ifndef USERSPACE
+#define USERSPACE
+
+#include "quantum.h"
+
+void my_custom_function(void);
+
+#endif

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/>.

users/_example/rules.mk

@@ -0,0 +1 @@
+SRC += _example.c

users/jackhumbert/jackhumbert.c

@@ -0,0 +1 @@
+#include "jackhumbert.h"

users/jackhumbert/jackhumbert.h

@@ -0,0 +1,6 @@
+#ifndef USERSPACE
+#define USERSPACE
+
+#include "quantum.h"
+
+#endif

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/>.

users/jackhumbert/rules.mk

@@ -0,0 +1 @@
+SRC += jackhumbert.c

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.