Skip to content

Alternative Compile QMK Quick Start Guide

Jump to bottom
LastContinue edited this page Jul 20, 2020 · 11 revisions

So you have decided you're going to need to compile QMK. Congratulations. 🎉

If you follow the steps on Massdrop's Official Docs you can get started. One of those links will eventually point you towards QMK's Newb's Guide which is really what this page is about.

It's not difficult to follow along, however it assumes that you have

  • Git installed
  • Homebrew Installed (if you're on a Mac)
  • MSYS2 or WSL installed and setup (if you're on Windows)
  • Python
  • probably something else I can't think of at the moment

None of these are hard to install, but way overkill if all you want to do is change your keyboard layout in a way you can't do via the GUI. If you get into this and really enjoy playing around, then you can always do it "the right way" later.

If you want a "bare minimum" software install do this instead:

TL;DR:

  • Download qmk in .zip form
  • Download and install Docker for either Mac or Windows
  • Do changes in QMK
  • Compile with docker run -e keymap=<whatever you called your keymap> -e keyboard=massdrop/ctrl --rm -v <wherever you unzipped qmk>:/qmk:rw edasque/qmk_firmware (See note for an alternative image)
  • Load onto board (I'd use QMK Toolbox the first few times I did this before branching off into more automated stuff like these scriptsMac or this scriptWin)

Detailed Explaination

  1. Download the QMK source. https://github.com/Massdrop/qmk_firmware/archive/master.zip . Unzip that to you Desktop/somewhere you can get to it easily (Desktop is great)
  2. You'll need Docker. If you're not familiar, Docker is an easy way to run disposable virtual machines. It's great for notoriously hard to install stuff like Ruby, Python, or in our case, a POSIX C development environment. Docker is a breeze to install as you can just click a few times and get setup. You will need a bit of hard drive space, but in terms of simplicity, it can't be beat. https://www.docker.com/get-started will ask that you create an account first, but who has time for that bullshit? https://download.docker.com/mac/stable/Docker.dmg or https://download.docker.com/win/stable/Docker%20for%20Windows%20Installer.exe depending on your system (If you really get into using Docker, an account is handy but again, you can "do it right" later). It might take a bit of time, but eventually it should start. I can't remember if it asks you any questions during the install, but for the most part the default settings are fine. Eventually you'll see a whale shaped 🐳 icon in your task bar and that means you're ready to go (you may need to restart).
  3. Once Docker is running, and you have QMK source, you're 90% there. The rest of this is wordy but relatively quick and pretty darn easy. Lets do a quick check. Open either your terminal (Mac, by typing cmd+space and typing "terminal") or Powershell (windows key and start typing "Powershell"). Run this command docker ps. It should return a blank line that says something like CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES If it doesn't return that, then you've gone off somewhere. Google will probably have the answer.
  4. Open the file you want to edit inside of your QMK directory. For keymapping/colors it will probably be something like /qmk/keyboards/massdrop/ctrl/keymaps/<whatever keymap>. Make your changes and save.
  5. Now back to Powershell/Terminal. Navigate to the same directory that you unziped QMK into. It will be something like cd ~/Desktop if you put it on the desktop.
  6. docker run -e keymap=<whatever keymap> -e keyboard=massdrop/ctrl --rm -v <wherever you unzipped qmk>:/qmk:rw edasque/qmk_firmware The first time you do this, it's gonna scroll with a lot of text, but eventually it will build (unless you made a syntax error, but it should be pretty verbose about what happened)
  7. Now by default, QMK builds its targets to <wherever you put qmk>/massdrop_ctrl_<whatever_map_you_used>.bin. You can use that file to load onto the board

Notes

There's a slightly faster Docker container I found. You can run it like
docker run -e KEYMAP=<keymap name> -e KEYBOARD=massdrop/ctrl --rm -v <whever you put qmk>:/qmk_firmware:rw qmkfm/qmk_firmware
However it is picky about the casing of the KEYMAP and KEYBOARD flags

Clone this wiki locally