[jackhill/qmk/firmware.git] / docs / getting_started_vagrant.md

# Vagrant Quick Start

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.

## Requirements

Using the `/Vagrantfile` in this repository requires you have [Vagrant](http://www.vagrantup.com/) as well as [VirtualBox](https://www.virtualbox.org/) (or [VMware Workstation](https://www.vmware.com/products/workstation) and [Vagrant VMware plugin](http://www.vagrantup.com/vmware) but the (paid) VMware plugin requires a licensed copy of VMware Workstation/Fusion).

*COMPATIBILITY NOTICE* 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:** `vagrant plugin install vagrant-vbguest`

Other than having Vagrant and Virtualbox 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 a Linux virtual machine 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.

# Flashing the Firmware

The "easy" way to flash the firmware is using a tool from your host OS:

* [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (recommended)
* [Teensy Loader](https://www.pjrc.com/teensy/loader.html)
* [Atmel FLIP](http://www.atmel.com/tools/flip.aspx)

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.
Commit	Line	Data
0ded95b8	1	# Vagrant Quick Start
995c3141 JH	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 [VirtualBox](https://www.virtualbox.org/) (or [VMware Workstation](https://www.vmware.com/products/workstation) and [Vagrant VMware plugin](http://www.vagrantup.com/vmware) but the (paid) VMware plugin requires a licensed copy of VMware Workstation/Fusion).
	8
	9	COMPATIBILITY NOTICE 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: `vagrant plugin install vagrant-vbguest`
	10
995c3141 JH	11	Other than having Vagrant and Virtualbox 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 a Linux virtual machine 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.
995c3141 JH	12
7b0356d1	13	# Flashing the Firmware
995c3141	14
0ded95b8	15	The "easy" way to flash the firmware is using a tool from your host OS:
995c3141	16
af37bb2f	17	* [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (recommended)
0ded95b8	18	* [Teensy Loader](https://www.pjrc.com/teensy/loader.html)
0ded95b8	19	* [Atmel FLIP](http://www.atmel.com/tools/flip.aspx)
995c3141 JH	20
995c3141 JH	21	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.