QMK Userspace (qmk#22222)

Co-authored-by: Duncan Sutherland <[email protected]>

Makefile

@@ -38,6 +38,11 @@ $(info QMK Firmware $(QMK_VERSION))
 endif
 endif
 
+# Try to determine userspace from qmk config, if set.
+ifeq ($(QMK_USERSPACE),)
+ QMK_USERSPACE = $(shell qmk config -ro user.overlay_dir | cut -d= -f2 | sed -e 's@^None$$@@g')
+endif
+
 # Determine which qmk cli to use
 QMK_BIN := qmk
 
@@ -191,9 +196,20 @@ define PARSE_KEYBOARD
  KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_4)/keymaps/*/.)))
  KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_5)/keymaps/*/.)))
 
+ ifneq ($(QMK_USERSPACE),)
+ KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(QMK_USERSPACE)/keyboards/$$(KEYBOARD_FOLDER_PATH_1)/keymaps/*/.)))
+ KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(QMK_USERSPACE)/keyboards/$$(KEYBOARD_FOLDER_PATH_2)/keymaps/*/.)))
+ KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(QMK_USERSPACE)/keyboards/$$(KEYBOARD_FOLDER_PATH_3)/keymaps/*/.)))
+ KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(QMK_USERSPACE)/keyboards/$$(KEYBOARD_FOLDER_PATH_4)/keymaps/*/.)))
+ KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(QMK_USERSPACE)/keyboards/$$(KEYBOARD_FOLDER_PATH_5)/keymaps/*/.)))
+ endif
+
  KEYBOARD_LAYOUTS := $(shell $(QMK_BIN) list-layouts --keyboard $1)
  LAYOUT_KEYMAPS :=
  $$(foreach LAYOUT,$$(KEYBOARD_LAYOUTS),$$(eval LAYOUT_KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/layouts/*/$$(LAYOUT)/*/.)))))
+ ifneq ($(QMK_USERSPACE),)
+ $$(foreach LAYOUT,$$(KEYBOARD_LAYOUTS),$$(eval LAYOUT_KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(QMK_USERSPACE)/layouts/$$(LAYOUT)/*/.)))))
+ endif
 
  KEYMAPS := $$(sort $$(KEYMAPS) $$(LAYOUT_KEYMAPS))
 
@@ -431,8 +447,18 @@ clean:
  rm -rf $(BUILD_DIR)
  echo 'done.'
 
-.PHONY: distclean
-distclean: clean
+.PHONY: distclean distclean_qmk
+distclean: distclean_qmk
+distclean_qmk: clean
  echo -n 'Deleting *.bin, *.hex, and *.uf2 ... '
  rm -f *.bin *.hex *.uf2
  echo 'done.'
+
+ifneq ($(QMK_USERSPACE),)
+.PHONY: distclean_userspace
+distclean: distclean_userspace
+distclean_userspace: clean
+ echo -n 'Deleting userspace *.bin, *.hex, and *.uf2 ... '
+ rm -f $(QMK_USERSPACE)/*.bin $(QMK_USERSPACE)/*.hex $(QMK_USERSPACE)/*.uf2
+ echo 'done.'
+endif

builddefs/build_json.mk

@@ -15,3 +15,22 @@ else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.json)","")
  KEYMAP_JSON := $(MAIN_KEYMAP_PATH_1)/keymap.json
  KEYMAP_JSON_PATH := $(MAIN_KEYMAP_PATH_1)
 endif
+
+ifneq ($(QMK_USERSPACE),)
+ ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_5)/keymap.json)","")
+ KEYMAP_JSON := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_5)/keymap.json
+ KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_5)
+ else ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_4)/keymap.json)","")
+ KEYMAP_JSON := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_4)/keymap.json
+ KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_4)
+ else ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_3)/keymap.json)","")
+ KEYMAP_JSON := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_3)/keymap.json
+ KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_3)
+ else ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_2)/keymap.json)","")
+ KEYMAP_JSON := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_2)/keymap.json
+ KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_2)
+ else ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_1)/keymap.json)","")
+ KEYMAP_JSON := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_1)/keymap.json
+ KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_1)
+ endif
+endif

builddefs/build_keyboard.mk

@@ -127,34 +127,60 @@ include $(INFO_RULES_MK)
 include $(BUILDDEFS_PATH)/build_json.mk
 
 # Pull in keymap level rules.mk
-# Look through the possible keymap folders until we find a matching keymap.c
-ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.c)","")
- -include $(MAIN_KEYMAP_PATH_1)/rules.mk
- KEYMAP_C := $(MAIN_KEYMAP_PATH_1)/keymap.c
- KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
-else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_2)/keymap.c)","")
- -include $(MAIN_KEYMAP_PATH_2)/rules.mk
- KEYMAP_C := $(MAIN_KEYMAP_PATH_2)/keymap.c
- KEYMAP_PATH := $(MAIN_KEYMAP_PATH_2)
-else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_3)/keymap.c)","")
- -include $(MAIN_KEYMAP_PATH_3)/rules.mk
- KEYMAP_C := $(MAIN_KEYMAP_PATH_3)/keymap.c
- KEYMAP_PATH := $(MAIN_KEYMAP_PATH_3)
-else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_4)/keymap.c)","")
- -include $(MAIN_KEYMAP_PATH_4)/rules.mk
- KEYMAP_C := $(MAIN_KEYMAP_PATH_4)/keymap.c
- KEYMAP_PATH := $(MAIN_KEYMAP_PATH_4)
-else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_5)/keymap.c)","")
- -include $(MAIN_KEYMAP_PATH_5)/rules.mk
- KEYMAP_C := $(MAIN_KEYMAP_PATH_5)/keymap.c
- KEYMAP_PATH := $(MAIN_KEYMAP_PATH_5)
-else ifneq ($(LAYOUTS),)
- # If we haven't found a keymap yet fall back to community layouts
- include $(BUILDDEFS_PATH)/build_layout.mk
-# Not finding keymap.c is fine if we found a keymap.json
-else ifeq ("$(wildcard $(KEYMAP_JSON_PATH))", "")
- $(call CATASTROPHIC_ERROR,Invalid keymap,Could not find keymap)
- # this state should never be reached
+ifeq ("$(wildcard $(KEYMAP_PATH))", "")
+ # Look through the possible keymap folders until we find a matching keymap.c
+ ifneq ($(QMK_USERSPACE),)
+ ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_1)/keymap.c)","")
+ -include $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_1)/rules.mk
+ KEYMAP_C := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_1)/keymap.c
+ KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_1)
+ else ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_2)/keymap.c)","")
+ -include $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_2)/rules.mk
+ KEYMAP_C := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_2)/keymap.c
+ KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_2)
+ else ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_3)/keymap.c)","")
+ -include $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_3)/rules.mk
+ KEYMAP_C := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_3)/keymap.c
+ KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_3)
+ else ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_4)/keymap.c)","")
+ -include $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_4)/rules.mk
+ KEYMAP_C := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_4)/keymap.c
+ KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_4)
+ else ifneq ("$(wildcard $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_5)/keymap.c)","")
+ -include $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_5)/rules.mk
+ KEYMAP_C := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_5)/keymap.c
+ KEYMAP_PATH := $(QMK_USERSPACE)/$(MAIN_KEYMAP_PATH_5)
+ endif
+ endif
+ ifeq ($(KEYMAP_PATH),)
+ ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.c)","")
+ -include $(MAIN_KEYMAP_PATH_1)/rules.mk
+ KEYMAP_C := $(MAIN_KEYMAP_PATH_1)/keymap.c
+ KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
+ else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_2)/keymap.c)","")
+ -include $(MAIN_KEYMAP_PATH_2)/rules.mk
+ KEYMAP_C := $(MAIN_KEYMAP_PATH_2)/keymap.c
+ KEYMAP_PATH := $(MAIN_KEYMAP_PATH_2)
+ else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_3)/keymap.c)","")
+ -include $(MAIN_KEYMAP_PATH_3)/rules.mk
+ KEYMAP_C := $(MAIN_KEYMAP_PATH_3)/keymap.c
+ KEYMAP_PATH := $(MAIN_KEYMAP_PATH_3)
+ else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_4)/keymap.c)","")
+ -include $(MAIN_KEYMAP_PATH_4)/rules.mk
+ KEYMAP_C := $(MAIN_KEYMAP_PATH_4)/keymap.c
+ KEYMAP_PATH := $(MAIN_KEYMAP_PATH_4)
+ else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_5)/keymap.c)","")
+ -include $(MAIN_KEYMAP_PATH_5)/rules.mk
+ KEYMAP_C := $(MAIN_KEYMAP_PATH_5)/keymap.c
+ KEYMAP_PATH := $(MAIN_KEYMAP_PATH_5)
+ else ifneq ($(LAYOUTS),)
+ # If we haven't found a keymap yet fall back to community layouts
+ include $(BUILDDEFS_PATH)/build_layout.mk
+ else ifeq ("$(wildcard $(KEYMAP_JSON_PATH))", "") # Not finding keymap.c is fine if we found a keymap.json
+ $(call CATASTROPHIC_ERROR,Invalid keymap,Could not find keymap)
+ # this state should never be reached
+ endif
+ endif
 endif
 
 # Have we found a keymap.json?
@@ -364,6 +390,16 @@ ifeq ("$(USER_NAME)","")
 endif
 USER_PATH := users/$(USER_NAME)
 
+# If we have userspace, then add it to the lookup VPATH
+ifneq ($(wildcard $(QMK_USERSPACE)),)
+ VPATH += $(QMK_USERSPACE)
+endif
+
+# If the equivalent users directory exists in userspace, use that in preference to anything currently in the main repo
+ifneq ($(wildcard $(QMK_USERSPACE)/$(USER_PATH)),)
+ USER_PATH := $(QMK_USERSPACE)/$(USER_PATH)
+endif
+
 # Pull in user level rules.mk
 -include $(USER_PATH)/rules.mk
 ifneq ("$(wildcard $(USER_PATH)/config.h)","")
@@ -404,6 +440,10 @@ ifneq ("$(KEYMAP_H)","")
  CONFIG_H += $(KEYMAP_H)
 endif
 
+ifeq ($(KEYMAP_C),)
+ $(call CATASTROPHIC_ERROR,Invalid keymap,Could not find keymap)
+endif
+
 OPT_DEFS += -DKEYMAP_C=\"$(KEYMAP_C)\"
 
 # If a keymap or userspace places their keymap array in another file instead, allow for it to be included

builddefs/build_layout.mk

@@ -1,6 +1,10 @@
 LAYOUTS_PATH := layouts
 LAYOUTS_REPOS := $(patsubst %/,%,$(sort $(dir $(wildcard $(LAYOUTS_PATH)/*/))))
 
+ifneq ($(QMK_USERSPACE),)
+ LAYOUTS_REPOS += $(patsubst %/,%,$(QMK_USERSPACE)/$(LAYOUTS_PATH))
+endif
+
 define SEARCH_LAYOUTS_REPO
  LAYOUT_KEYMAP_PATH := $$(LAYOUTS_REPO)/$$(LAYOUT)/$$(KEYMAP)
  LAYOUT_KEYMAP_JSON := $$(LAYOUT_KEYMAP_PATH)/keymap.json

builddefs/common_rules.mk

@@ -191,7 +191,7 @@ DFU_SUFFIX_ARGS ?=
 elf: $(BUILD_DIR)/$(TARGET).elf
 hex: $(BUILD_DIR)/$(TARGET).hex
 uf2: $(BUILD_DIR)/$(TARGET).uf2
-cpfirmware: $(FIRMWARE_FORMAT)
+cpfirmware_qmk: $(FIRMWARE_FORMAT)
  $(SILENT) || printf "Copying $(TARGET).$(FIRMWARE_FORMAT) to qmk_firmware folder" | $(AWK_CMD)
  $(COPY) $(BUILD_DIR)/$(TARGET).$(FIRMWARE_FORMAT) $(TARGET).$(FIRMWARE_FORMAT) && $(PRINT_OK)
 eep: $(BUILD_DIR)/$(TARGET).eep
@@ -200,6 +200,15 @@ sym: $(BUILD_DIR)/$(TARGET).sym
 LIBNAME=lib$(TARGET).a
 lib: $(LIBNAME)
 
+cpfirmware: cpfirmware_qmk
+
+ifneq ($(QMK_USERSPACE),)
+cpfirmware: cpfirmware_userspace
+cpfirmware_userspace: cpfirmware_qmk
+ $(SILENT) || printf "Copying $(TARGET).$(FIRMWARE_FORMAT) to userspace folder" | $(AWK_CMD)
+ $(COPY) $(BUILD_DIR)/$(TARGET).$(FIRMWARE_FORMAT) $(QMK_USERSPACE)/$(TARGET).$(FIRMWARE_FORMAT) && $(PRINT_OK)
+endif
+
 # Display size of file, modifying the output so people don't mistakenly grab the hex output
 BINARY_SIZE = $(SIZE) --target=$(FORMAT) $(BUILD_DIR)/$(TARGET).hex | $(SED) -e 's/\.build\/.*$$/$(TARGET).$(FIRMWARE_FORMAT)/g'
 

data/schemas/definitions.jsonschema

@@ -177,5 +177,23 @@
  "type": "integer",
  "minimum": 0,
  "maximum": 1
+ },
+ "keyboard_keymap_tuple": {
+ "type": "array",
+ "prefixItems": [
+ { "$ref": "#/keyboard" },
+ { "$ref": "#/filename" }
+ ],
+ "unevaluatedItems": false
+ },
+ "json_file_path": {
+ "type": "string",
+ "pattern": "^[0-9a-z_/\\-]+\\.json$"
+ },
+ "build_target": {
+ "oneOf": [
+ { "$ref": "#/keyboard_keymap_tuple" },
+ { "$ref": "#/json_file_path" }
+ ]
  }
 }

data/schemas/user_repo_v0.jsonschema

@@ -0,0 +1,14 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema#",
+ "$id": "qmk.user_repo.v0",
+ "title": "User Repository Information",
+ "type": "object",
+ "required": [
+ "userspace_version"
+ ],
+ "properties": {
+ "userspace_version": {
+ "type": "string",
+ },
+ }
+}

data/schemas/user_repo_v1.jsonschema

@@ -0,0 +1,22 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema#",
+ "$id": "qmk.user_repo.v1",
+ "title": "User Repository Information",
+ "type": "object",
+ "required": [
+ "userspace_version",
+ "build_targets"
+ ],
+ "properties": {
+ "userspace_version": {
+ "type": "string",
+ "enum": ["1.0"]
+ },
+ "build_targets": {
+ "type": "array",
+ "items": {
+ "$ref": "qmk.definitions.v1#/build_target"
+ }
+ }
+ }
+}

docs/_summary.md

@@ -4,7 +4,7 @@
  * [Building Your First Firmware](newbs_building_firmware.md)
  * [Flashing Firmware](newbs_flashing.md)
  * [Getting Help/Support](support.md)
- * [Building With GitHub Userspace](newbs_building_firmware_workflow.md)
+ * [External Userspace](newbs_external_userspace.md)
  * [Other Resources](newbs_learn_more_resources.md)
  * [Syllabus](syllabus.md)