docs/getting_started_vagrant.md

   1 # Vagrant Quick Start
   2
   3 This project includes a `Vagrantfile` 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 using the Vagrantfile to build. This makes it much easier for people to help you troubleshoot any issues you encounter.
   4
   5 ## Requirements
   6
   7 Using the `Vagrantfile` in this repository requires you have [Vagrant](http://www.vagrantup.com/) as well as a supported provider installed:
   8
   9 * [VirtualBox](https://www.virtualbox.org/) (Version at least 5.0.12)
  10   * Sold as 'the most accessible platform to use Vagrant'
  11 * [VMware Workstation](https://www.vmware.com/products/workstation) and [Vagrant VMware plugin](http://www.vagrantup.com/vmware)
  12   * The (paid) VMware plugin requires a licensed copy of VMware Workstation/Fusion
  13 * [Docker](https://www.docker.com/)
  14
  15 Other than having Vagrant, a suitable provider installed and possibly a restart of your computer afterwards, you can simple run a 'vagrant up' anywhere inside the folder where you checked out this project and it will start an environment (either a virtual machine or container) that contains all the tools required to build this project. There is a post Vagrant startup hint that will get you off on the right foot, otherwise you can also reference the build documentation below.
  16
  17 ## Flashing the Firmware
  18
  19 The "easy" way to flash the firmware is using a tool from your host OS:
  20
  21 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (recommended)
  22 * [Teensy Loader](https://www.pjrc.com/teensy/loader.html)
  23 * [Atmel FLIP](http://www.atmel.com/tools/flip.aspx)
  24
  25 If you want to program via the command line you can uncomment the ['modifyvm'] lines in the Vagrantfile to enable the USB passthrough into Linux and then program using the command line tools like dfu-util/dfu-programmer or you can install the Teensy CLI version.
  26
  27 ## Vagrantfile Overview
  28 The development environment is configured to run the QMK Docker image, `qmkfm/base_container`. This not only ensures predictability between systems, it also mirrors the CI environment.
  29
  30 ## FAQ
  31
  32 ### Why am I seeing issues under Virtualbox?
  33 Certain versions of Virtualbox 5 appear to have an incompatibility with the Virtualbox extensions installed in the boxes in this Vagrantfile. If you encounter any issues with the /vagrant mount not succeeding, please upgrade your version of Virtualbox to at least 5.0.12. **Alternately, you can try running the following command:**
  34
  35 ```console
  36 vagrant plugin install vagrant-vbguest
  37 ```
  38
  39 ### How do I remove an existing environment?
  40 Finished with your environment? From anywhere inside the folder where you checked out this project, Execute:
  41
  42 ```console
  43 vagrant destory
  44 ```
  45
  46 ### What if I want to use Docker directly?
  47 Want to benefit from the Vagrant workflow without a virtual machine? The Vagrantfile is configured to bypass running a virtual machine, and run the container directly. Execute the following when bringing up the environment to force the use of Docker:
  48 ```console
  49 vagrant up --provider=docker
  50 ```
  51
  52 ### How do I access the virtual machine instead of the Docker container?
  53 Execute the following to bypass the `vagrant` user booting directly to the official qmk builder image:
  54
  55 ```console
  56 vagrant ssh -c 'sudo -i'
  57 ```