mirrors/qmk_firmware
1
0
Fork 1
mirror of https://github.com/qmk/qmk_firmware synced 2024-11-17 17:35:30 +00:00
Code Issues Projects Releases Packages Wiki Activity

Reintegrate previous docker docs (#9084)

Browse source
This commit is contained in:
Joel Challis 2020-05-20 05:54:55 +01:00 committed by GitHub
parent ddca422776
commit 0fbcb41c85
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 50 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/_summary.md
View file

@ -34,6 +34,8 @@
* [Customizing Functionality](custom_quantum_functions.md)
* [Driver Installation with Zadig](driver_installation_zadig.md)
* [Keymap Overview](keymap.md)
* Development Environments
* [Docker Guide](getting_started_docker.md)
* [Vagrant Guide](getting_started_vagrant.md)
* Flashing
* [Flashing](flashing.md)

47
docs/getting_started_docker.md Normal file
View file

@ -0,0 +1,47 @@
# 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` install.
* [Docker CE](https://docs.docker.com/install/#supported-platforms)
## Usage
Acquire a local copy of the QMK's repository (including submodules):
```bash
git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
cd qmk_firmware
```
Run the following command to build a keymap:
```bash
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:
```bash
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:
```bash
util/docker_build.sh
# Reads parameters as input (leave blank for all keyboards/keymaps)
```
## FAQ
### Why can't I flash on Windows/macOS
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](https://github.com/qmk/qmk_toolbox) instead.
!> 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**.