Proposal: QMK Userspace Improvements

[skullydazed]

To facilitate users storing their keymaps and custom code in an external repository we are looking into extending how userspace works.

How Userspace Works Today

Today we have qmk_firmware/users/<username> which contains one or more of the following files:

• config.h
• <username>.c
• <username>.h
• rules.mk

When a keymap of the name <username> is compile our make infrastructure will also pull in the rules.mk file, include the config.h file, and add users/<username.c> to SRC so that it is compiled as well.

What We Want To Add

In short, we want to support storing keymaps in userspace. This will involve supporting two new directories in userspace- keymaps and layouts.

Keymaps

The keymaps directory can be laid out in one of two different ways:

1. users/<username>/keymaps/<keyboard_folder_with_subdirs>/keymap.{c,json}
2. users/<username>/keymaps/<keyboard_name_with_underscores_keymap_name>.{c,json}

Some examples to demonstrate each format:

1:

• users/skully/keymaps/clueboard/66/keymap.json
• users/jackhumbert/keymaps/planck/rev5/keymap.json
• users/drashna/keymaps/ergodox_ez/keymap.json

2:

• users/skully/keymaps/clueboard_66_keymap.json
• users/jackhumbert/keymaps/planck_rev5_keymap.json
• users/drashna/keymaps/ergodox_ez_keymap.json

For the sake of not confusing new users we will document #1 in all tutorial and reference documentation, while #2 will be documented for those who wish to use it instead but will not be used in any examples.

Users will be able to add rules.mk and config.h for keymap specific settings as well.

Layouts

Layouts, being keyboard agnostic, can be arranged in a single directory without any hierarchy:

users/<username>/layouts/<layout_name>/keymap.{c,json}

Like keymaps, users will be able to put a rules.mk and config.h file into this directory.

[zekth]

This needs also work on the cli like commands:

qmk add_user zekth
qmk sync_user zekth

To make the usage of git easier.

[noroadsleft]

I'm selfishly glad that it seems Format 1 is the preferred direction, if only because I have a rather large QMK Configurator update planned that actually restructures the default keymaps on that repo to a very similar directory structure.

(Said Configurator update is probably about 2/3rds complete and fully functional at this point.)