If you're using homebrew, you can use the following commands:
brew tap osx-cross/avr
brew install avr-libc
brew install dfu-programmer
This is the recommended method. If you don't have homebrew, install it! It's very much worth it for anyone who works in the command line.
You can also try these instructions:
Xcode->Preferences->Downloads
.Install AVR GCC, AVR libc, and dfu-progammer with your favorite package manager.
Debian/Ubuntu example:
sudo apt-get update
sudo apt-get install gcc-avr avr-libc dfu-programmer
If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the VAGRANT_GUIDE file.
qmk_firmware
folder using the cd
command. The command prompt will typically open to your home directory. If, for example, you cloned the repository to your Documents folder, then you would type cd Documents/qmk_firmware
. If you extracted the file from a zip, then it may be named qmk_firmware-master
instead.dir
command on Windows, or the ls
command on Linux or Mac. You should see several files, including README.md
and a quantum
folder. From here, you need to navigate to the appropriate folder under keyboard/
. For example, if you're building for a Planck, run cd keyboard/planck
.make
command. This should output a lot of information about the build process. More information about the make
command can be found below.The make
command is how you compile the firmware into a .hex file, which can be loaded by a dfu programmer (like dfu-progammer via make dfu
) or the Teensy loader (only used with Teensys). You can run make
from the root (/
), your keyboard folder (/keyboard/<keyboard>/
), or your keymap folder (/keyboard/<keyboard>/keymaps/<keymap>/
) if you have a Makefile
there (see the example here).
By default, this will generate a <keyboard>_<keymap>.hex
file in whichever folder you run make
from. These files are ignored by git, so don't worry about deleting them when committing/creating pull requests. Your .hex file will also be copied into your keymap folder as compiled.hex
, which isn't ignored by git - this is included in case first-time users are having trouble compiling, and just want to flash a layout via make dfu-no-build
or using the Teensy loader.
/
) folder is the qmk_firmware folder, in which are doc
, keyboard
, quantum
, etc./keyboard/planck
./keyboard/planck/keymaps/default
.Below is a list of the useful make
commands in QMK:
make
- cleans automatically and builds your keyboard and keymap depending on which folder you're in. This defaults to the "default" layout (unless in a keymap folder), and Planck keyboard in the root folder
make keyboard=<keyboard>
- specifies the keyboard (only to be used in root)make keymap=<keymap>
- specifies the keymap (only to be used in root and keyboard folder - not needed when in keymap folder)make quick
- skips the clean step (cannot be used immediately after modifying config.h or Makefiles)make dfu
- (requires dfu-programmer) builds and flashes the keymap to your keyboard once placed in reset/dfu mode (button or press KC_RESET
). This does not work for Teensy-based keyboards like the ErgoDox EZ.
keyboard=
and keymap=
are compatible with thismake dfu-no-build
- (requires dfu-programmer) same as make dfu
, but doesn't build and uses the included compiled.hex
to flash the keyboardmake all-keyboards
- builds all keymaps for all keyboards and outputs status of each (use in root)make all-keyboards-default
- builds all default keymaps for all keyboards and outputs status of each (use in root)make all-keymaps [keyboard=<keyboard>]
- builds all of the keymaps for whatever keyboard folder you're in, or specified by <keyboard>
make all-keyboards-quick
, make all-keyboards-default-quick
and make all-keymaps-quick [keyboard=<keyboard>]
- like the normal "make-all-*" commands, but they skip the clean stepsOther, less useful functionality:
make COLOR=false
- turns off color outputmake SILENT=true
- turns off output besides errors/warningsmake VERBOSE=true
- outputs all of the avr-gcc stuff (not interesting)There are 3 different make
and Makefile
locations:
/
)/keyboard/<keyboard>/
)/keyboard/<keyboard>/keymaps/<keymap>/
)The root contains the code used to automatically figure out which keymap or keymaps to compile based on your current directory and commandline arguments. It's considered stable, and shouldn't be modified. The keyboard one will contain the MCU set-up and default settings for your keyboard, and shouldn't be modified unless you are the producer of that keyboard. The keymap Makefile can be modified by users, and is optional. It is included automatically if it exists. You can see an example here - the last few lines are the most important. The settings you set here will override any defaults set in the keyboard Makefile. It is required if you want to run make
in the keymap folder.
config.h
fileThere are 2 config.h
locations:
/keyboard/<keyboard>/
)/keyboard/<keyboard>/keymaps/<keymap>/
)The keyboard config.h
is included only if the keymap one doesn't exist. The format to use for your custom one is here. If you want to override a setting from the parent config.h
file, you need to do this:
#undef MY_SETTING
#define MY_SETTING 4
```c
For a value of `4` for this imaginary setting. So we `undef` it first, then `define` it.
You can then override any settings, rather than having to copy and paste the whole thing.