lunny/qmk_firmware-mirror
1
0
Fork 0
mirror of https://github.com/qmk/qmk_firmware synced 2024-12-22 16:36:58 +00:00
Code Issues Packages Projects Releases Wiki Activity
qmk_firmware-mirror/docs/getting_started_docker.md
Max Audron e4d3ff2374
Add support for using podman to util/docker_build.sh (#10819) 
* add podman support to docker_build.sh script

* break out runtime into the RUNTIME variable
* allows RUNTIME to be set by the user
* decides on docker or podman if docker isn't avaible
* rewrote check for docker-machine to account only for docker runtime
* put --user arg into a variable only to be used with docker
  this is not needed with podman as podman maps the containers root id
  to the users id.

* add podman to getting_started_docker documentation
2021-02-28 15:59:42 +11:00

2.6 KiB
Raw Blame History

Docker Quick Start

This project includes a Docker workflow that will allow you to build a new firmware for your keyboard very easily without major changes to your primary operating system. This also ensures that when you clone the project and perform a build, you have the exact same environment as anyone else and the QMK build infrastructure. This makes it much easier for people to help you troubleshoot any issues you encounter.

Requirements

The main prerequisite is a working docker or podman install.

Usage

Acquire a local copy of the QMK's repository (including submodules):

git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
cd qmk_firmware

Run the following command to build a keymap:

util/docker_build.sh <keyboard>:<keymap>
# For example: util/docker_build.sh planck/rev6:default

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, all keymaps are used. Note that the parameter format is the same as when building with make.

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

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 all keyboards/keymaps)

You can manually set which container runtime you want to use by setting the RUNTIME environment variable to it's name or path. By default docker or podman are automatically detected and docker is preferred over podman.

RUNTIME="podman" util/docker_build.sh keyboard:keymap:target

FAQ

Why can't I flash on Windows/macOS

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.