qmk_firmware/docs/getting_started_build_tools.md

Installing Build Tools

This page describes setting up the build environment for QMK. These instructions cover AVR processors (such as the atmega32u4).

Note: If this is your first time here, check out the Complete Newbs Guide page.

Before continuing, double check that your submodules (third-party libraries) are up to date by running make git-submodule.

Linux

To ensure you are always up to date, you can just run sudo util/qmk_install.sh. That should always install all the dependencies needed. This will run apt-get upgrade.

You can also install things manually, but this documentation might not be always up to date with all requirements.

The current requirements are the following, but not all might be needed depending on what you do. Also note that some systems might not have all the dependencies available as packages, or they might be named differently.

build-essential
gcc
unzip
wget
zip
gcc-avr
binutils-avr
avr-libc
dfu-programmer
dfu-util
gcc-arm-none-eabi
binutils-arm-none-eabi
libnewlib-arm-none-eabi
git

Install the dependencies with your favorite package manager.

Debian / Ubuntu example:

sudo apt-get update
sudo apt-get install gcc unzip wget zip gcc-avr binutils-avr avr-libc dfu-programmer dfu-util gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi

Fedora / Red Hat example:

sudo dnf install gcc unzip wget zip dfu-util dfu-programmer avr-gcc avr-libc binutils-avr32-linux-gnu arm-none-eabi-gcc-cs arm-none-eabi-binutils-cs arm-none-eabi-newlib

Arch / Manjaro example:

pacman -S base-devel gcc unzip wget zip avr-gcc avr-binutils avr-libc dfu-util arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib git dfu-programmer dfu-util

Nix

If you're on NixOS, or have Nix installed on Linux or macOS, run nix-shell from the repository root to get a build environment.

By default, this will download compilers for both AVR and ARM. If you don't need both, disable the avr or arm arguments, e.g.:

nix-shell --arg arm false

macOS

If you're using Homebrew, you can use the following commands:

brew tap osx-cross/avr
brew tap osx-cross/arm
brew update
brew install avr-gcc@8
brew link --force avr-gcc@8
brew install dfu-programmer
brew install dfu-util
brew install arm-gcc-bin@8
brew link --force arm-gcc-bin@8
brew install avrdude

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. Note that the make and make install portion during the homebrew installation of avr-gcc@8 can take over 20 minutes and exhibit high CPU usage.

Windows with msys2 (recommended)

The best environment to use, for Windows Vista through any later version (tested on 7 and 10), is msys2.

• Install msys2 by downloading it and following the instructions here: http://www.msys2.org
• Open the MSYS2 MingGW 64-bit shortcut
• Navigate to your QMK repository. For example, if it's in the root of your c drive:
• $ cd /c/qmk_firmware
• Run util/qmk_install.sh and follow the prompts

Windows 10 (deprecated)

These are the old instructions for Windows 10. We recommend you use MSYS2 as outlined above.

Creators Update

If you have Windows 10 with Creators Update or later, you can build and flash the firmware directly. Before the Creators Update, only building was possible. If you don't have it yet or if are unsure, follow these instructions.

Windows Subsystem for Linux

In addition to the Creators Update, you need Windows 10 Subystem for Linux, so install it following these instructions. If you already have the Windows 10 Subsystem for Linux from the Anniversary update it's recommended that you upgrade it to 16.04LTS, because some keyboards don't compile with the toolchains included in 14.04LTS. Note that you need to know what your are doing if you chose the sudo do-release-upgrade method.

Git

If you already have cloned the repository on your Windows file system you can ignore this section.

You will need to clone the repository to your Windows file system using the normal Git for Windows and not the WSL Git. So if you haven't installed Git before, download and install it. Then set it up, it's important that you setup the e-mail and user name, especially if you are planning to contribute.

Once Git is installed, open the Git Bash command and change the directory to where you want to clone QMK; note that you have to use forward slashes, and that your c drive is accessed like this /c/path/to/where/you/want/to/go. Then run git clone --recurse-submodules https://github.com/qmk/qmk_firmware, this will create a new folder qmk_firmware as a subfolder of the current one.

Toolchain Setup

The Toolchain setup is done through the Windows Subsystem for Linux, and the process is fully automated. If you want to do everything manually, there are no other instructions than the scripts themselves, but you can always open issues and ask for more information.

1. Open "Bash On Ubuntu On Windows" from the start menu.
2. Go to the directory where you cloned qmk_firmware. Note that the paths start with /mnt/ in the WSL, so you have to write for example cd /mnt/c/path/to/qmk_firmware.
3. Run util/wsl_install.sh and follow the on-screen instructions.
4. Close the Bash command window, and re-open it.
5. You are ready to compile and flash the firmware!

Some Important Things to Keep in Mind

• You can run util/wsl_install.sh again to get all the newest updates.
• Your QMK repository need to be on a Windows file system path, since WSL can't run executables outside it.
• The WSL Git is not compatible with the Windows Git, so use the Windows Git Bash or a windows Git GUI for all Git operations
• You can edit files either inside WSL or normally using Windows, but note that if you edit makefiles or shell scripts, make sure you are using an editor that saves the files with Unix line endings. Otherwise the compilation might not work.

Docker

If this is a bit complex for you, Docker might be the turnkey solution you need. After installing Docker CE, run the following command from the qmk_firmware directory to build a keyboard/keymap:

util/docker_build.sh keyboard:keymap
# For example: util/docker_build.sh ergodox_ez:steno

This will compile the desired keyboard/keymap and leave the resulting .hex or .bin file in the QMK directory for you to flash. If :keymap is omitted, the default keymap is used. Note that the parameter format is the same as when building with make.

You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use:

util/docker_build.sh
# Reads parameters as input (leave blank for defaults)

There is also support for building and flashing the keyboard straight from Docker by specifying the target as well:

util/docker_build.sh keyboard:keymap:target
# For example: util/docker_build.sh planck/rev6:default:flash

If you're on Linux, this should work out of the box. On Windows and macOS, it requires Docker Machine to be running. This is tedious to set up, so it's not recommended; use QMK Toolbox instead.

!> Docker for Windows requires Hyper-V to be enabled. This means that it cannot work on versions of Windows which don't have Hyper-V, such as Windows 7, Windows 8 and Windows 10 Home.

Vagrant

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.