Kyria from SplitKB

Separate keymap repo for QMK

A while back I started getting into custom mechanical keyboards and the QMK firmware, a really fun side project. One issue I’ve faced since starting to create my own keymaps and custom functionality is that all my code have been living inside the massive qmk_firmware repository which means some extra headache when rebasing to get the latest features. This was especially clear recently when trying to rebase on the latest master branch after having cherry-picked a couple of PRs that were now merged. What I would like is to separate my code from the rest of the firmware, since I never change anything outside of my own folders anyway.

To sort this out I’d seen people use separate repositories for their custom code and symlink it when building. Having no experience whatsoever with that kind of black magic I started googling “QMK keymap separate repo” and to my surprise I couldn’t find any blog posts about it. So now that I’ve finally taken the time to set it up for myself, I thought I’d share the steps (it was a lot easier than I thought). What we’ll be doing is to create a new repository, add QMK as a submodule and create a make file handling the symlinks and build steps.

Update 2024

QMK now has support for external userspace
https://docs.qmk.fm/newbs_external_userspace

While I have only tried it out briefly, this is most likely a better way of doing things going forward as you don’t need error prone submodules and symlinks.

As an example, here is my repo with my common code and the configs for my Ferris Sweep: https://github.com/patrick-elmquist/qmk_userspace

Lily58 from Mechboards

First off, here’s a link to my ‘keymaps’ repository on Github, it’s what you will end up with when following the steps below:

GitHub - patrick-elmquist/qmk-keymaps: A user repository with my keymaps for QMK keyboards.

After following a discussion in #keymap-ideas on the SplitKB Discord, I ended up using the following repo as a template for how to set it up:

GitHub - grasegger/kyria-layout

Since I have more than one keyboard and a user space folder in qmk_firmware I needed to make some adjustments for it to suit my needs. These are the steps I went through:

Create a new Git repository and add QMK as a submodule

We don’t want to commit the build output to the repo, so add a .gitignore file with the following:

Update March 2023:
Do NOT name your repository (or at least the folder you clone into) keymapsas a recent change to QMK can make the builds fail with the following error:

qmk_firmware ❯ qmk compile -kb dz60 -km default
Ψ Compiling keymap with gmake --jobs=1 dz60:default


QMK Firmware 0.20.0
make: *** No rule to make target 'dz60:default'. Stop.
|
| QMK's make format is:
|     make keyboard_folder:keymap_folder[:target]
|
| Where `keyboard_folder` is the path to the keyboard relative to
| `qmk_firmware/keyboards/`, and `keymap_folder` is the name of the
| keymap folder under that board's `keymaps/` directory.
|
| Examples:
|     keyboards/dz60, keyboards/dz60/keymaps/default
|       -> make dz60:default
|       -> qmk compile -kb dz60 -km default
|     keyboards/planck/rev6, keyboards/planck/keymaps/default
|       -> make planck/rev6:default:flash
|       -> qmk flash -kb planck/rev6 -km default
|

QMK look for a folder called keymaps to find the provided keymap to compile and it seems having the repo folder called the same can cause conflicts.

Add folder structure

Now lets create the folder structure. In the qmk_firware repo I had keymaps for Lily58, Kyria and have common code for both in a user space folder. So this is this is the structure I use in the new repository:

keymaps/
 + kyria/ 
 + lily58/
 + user/
 | .gitignore
 ` .gitmodules 

Now transfer any files you already have inqmk_firmware/keyboards/<keyboard>/keymaps/ and qmk_firmaware/users/<user> folders to their new location. Note: if you’re transferring files to the user folder it assumes that you have already set up your user space with the correct files. If you haven’t, you can find a guide for how to do it here. Fore me the structure looked something like this after:

keymaps/
 + kyria/
 |  | keymap.c
 |  | config.h
 |  `rules.mk
 | 
 + lily58/
 |  | keymap.c
 |  | config.h
 |  `rules.mk
 |
 + user/
 |  | <user>.c
 |  | <user>.h
 |  ` ... more user files
 |
 | .gitignore
 ` .gitmodules

Create Makefile

When you’re done there’s only one more thing to do, and that’s to configure a Makefile to setup the symlinks and build the firmware. I should mention that prior to this I’ve never written a make file, so there might be better ways to do this, but I wanted to make it easy to add more boards.

Note: the Makefile assumes that the QMK CLI is installed.
Now we are pretty much done, to build, just go into the main folder and run:

Wrapping up

Kyria from SplitKB

That’s all I had to do to set it up. It’s been working great, I love to have the code separate from the main repo and also closer together making it easier to navigate while developing.