Add a better Docker build script + update Dockerfile (#4222)

* Add a Docker build script

* Add usage and error messages

* Add -r to reads

Thanks mechmerlin

* Add keyboard:keymap form, improve script

* Add target argument, change usage forms in script

* Add check for more than 3 args in keyboard:keymap:target form

* Change Docker base image to debian, use community repo

This matches what qmk_compiler uses (https://github.com/qmk/qmk_compiler/blob/master/Dockerfile#L1).

I've removed the maintainer as we now have a community build on Docker Hub (https://hub.docker.com/r/qmkfm/qmk_firmware). This Dockerfile will also be maintained by the community.

* Change build command format to keyboard:keymap

* Call make directly in container run command

* Simplify script, remove 3-arg form

* Add COPY to Dockerfile so images are usable in and of themselves

Also change WORKDIR from /qmk to /qmk_firmware

* Add USB pass-through for Linux and docker-machine hosts

* Read directly into variables instead of array

* Alphabetically sort dependencies in Dockerfile

* Set executable bit on util/docker_build.sh

* Update Docker docs

* Add warning about Docker on Windows

* Expand comment in docs

* Check docker-machine exit code instead of string

* Only match --help with whole arguments

* Make script POSIX-compliant

* Convert script indentation to tabs
This commit is contained in:
Konstantin Đorđević 2018-12-08 18:42:46 +01:00 committed by MechMerlin
parent 2ad2b73d68
commit 13ad650136
3 changed files with 84 additions and 31 deletions

View file

@ -1,28 +1,29 @@
FROM debian:jessie
MAINTAINER Erik Dasque <erik@frenchguys.com>
FROM debian
RUN apt-get update && apt-get install --no-install-recommends -y build-essential \
RUN apt-get update && apt-get install --no-install-recommends -y \
avr-libc \
avrdude \
binutils-arm-none-eabi \
binutils-avr \
build-essential \
dfu-programmer \
dfu-util \
gcc \
gcc-arm-none-eabi \
gcc-avr \
git \
libnewlib-arm-none-eabi \
software-properties-common \
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 \
software-properties-common \
avrdude \
&& rm -rf /var/lib/apt/lists/*
ENV keyboard=ergodox
ENV subproject=ez
ENV keymap=default
ENV KEYBOARD=ergodox_ez
ENV KEYMAP=default
VOLUME /qmk
WORKDIR /qmk
CMD make clean ; make keyboard=${keyboard} subproject=${subproject} keymap=${keymap}
VOLUME /qmk_firmware
WORKDIR /qmk_firmware
COPY . .
CMD make $KEYBOARD:$KEYMAP

View file

@ -123,24 +123,27 @@ If you have trouble and want to ask for help, it is useful to generate a *Win_Ch
## Docker
If this is a bit complex for you, Docker might be the turn-key solution you need. After installing [Docker](https://www.docker.com/products/docker), run the following command at the root of the QMK folder to build a keyboard/keymap:
If this is a bit complex for you, Docker might be the turn-key solution you need. After installing [Docker CE](https://docs.docker.com/install/#supported-platforms), run the following command from the `qmk_firmware` directory to build a keyboard/keymap:
```bash
# You'll run this every time you want to build a keymap
# modify the keymap and keyboard assignment to compile what you want
# defaults are ergodox/default
util/docker_build.sh keyboard:keymap
# For example: util/docker_build.sh ergodox_ez:steno
```
This will compile the targeted 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`.
docker run -e keymap=gwen -e keyboard=ergodox_ez --rm -v $('pwd'):/qmk:rw edasque/qmk_firmware
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:
```bash
util/docker_build.sh
# Reads parameters as input (leave blank for defaults)
```
On Windows Docker seems to have issues with the VOLUME tag in Dockerfile, and `$('pwd')` won't print a Windows compliant path; use full path instead, like this:
There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well:
```bash
docker run -e keymap=default -e keyboard=ergodox_ez --rm -v D:/Users/Sacapuces/Documents/Repositories/qmk:/qmk:rw edasque/qmk_firmware
util/docker_build.sh keyboard:keymap:target
# For example: util/docker_build.sh planck/rev6:default:dfu-util
```
If you're on Linux, this should work out of the box. On Windows and macOS, it requires [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) to be running. This is tedious to set up, so it's not recommended; use QMK Toolbox instead.
This will compile the targeted keyboard/keymap and leave it in your QMK directory for you to flash.
!> Docker for Windows requires [Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-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](getting_started_vagrant.md).

49
util/docker_build.sh Executable file
View file

@ -0,0 +1,49 @@
#!/bin/sh
# NOTE: This script uses tabs for indentation
USAGE="Usage: $0 [keyboard[:keymap[:target]]]"
# Check preconditions
for arg; do
if [ "$arg" = "--help" ]; then
echo "$USAGE"
exit 0
fi
done
if [ $# -gt 1 ]; then
echo "$USAGE" >&2
exit 1
elif ! command -v docker >/dev/null 2>&1; then
echo "Error: docker not found" >&2
echo "See https://docs.docker.com/install/#supported-platforms for installation instructions" >&2
exit 2
fi
# Determine arguments
if [ $# -eq 0 ]; then
printf "keyboard=" && read -r keyboard
[ -n "$keyboard" ] && printf "keymap=" && read -r keymap
[ -n "$keymap" ] && printf "target=" && read -r target
else
IFS=':' read -r keyboard keymap target x <<-EOF
$1
EOF
if [ -n "$x" ]; then
echo "$USAGE" >&2
exit 1
fi
fi
if [ -n "$target" ]; then
if [ "$(uname)" = "Linux" ] || docker-machine active >/dev/null 2>&1; then
usb_args="--privileged -v /dev/bus/usb:/dev/bus/usb"
else
echo "Error: target requires docker-machine to work on your platform" >&2
echo "See http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos" >&2
exit 3
fi
fi
dir=$(pwd -W 2>/dev/null) || dir=$PWD # Use Windows path if on Windows
# Run container and build firmware
docker run --rm $usb_args -v "$dir":/qmk_firmware qmkfm/qmk_firmware \
make "$keyboard${keymap:+:$keymap}${target:+:$target}"