From a399823b936e6b0eabd144c5a513dedf5f8450d2 Mon Sep 17 00:00:00 2001 From: Noah Andrews Date: Wed, 2 Mar 2016 21:53:55 -0500 Subject: Added stub BUILD_GUIDE.md --- BUILD_GUIDE.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 BUILD_GUIDE.md (limited to 'BUILD_GUIDE.md') diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md new file mode 100644 index 000000000..2a1eaa555 --- /dev/null +++ b/BUILD_GUIDE.md @@ -0,0 +1 @@ +# Build Guide \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 3871ced15c880cb6d4975e1f1c4fb009f0b37adf Mon Sep 17 00:00:00 2001 From: Noah Andrews Date: Wed, 2 Mar 2016 22:03:25 -0500 Subject: Added Vagrant explanation --- BUILD_GUIDE.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'BUILD_GUIDE.md') diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md index 2a1eaa555..272df46c8 100644 --- a/BUILD_GUIDE.md +++ b/BUILD_GUIDE.md @@ -1 +1,14 @@ -# Build Guide \ No newline at end of file +# Build Guide + +## Platform-specific setup + +### Windows + + +### Mac + + +### Linux + +### 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 file](VAGRANT_GUIDE.md). \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 92c3397ffc9cff22dee5a893023050492d31c4e3 Mon Sep 17 00:00:00 2001 From: Noah Andrews Date: Wed, 2 Mar 2016 22:07:26 -0500 Subject: Added placeholder for windows section of build guide --- BUILD_GUIDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'BUILD_GUIDE.md') diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md index 272df46c8..d7106d918 100644 --- a/BUILD_GUIDE.md +++ b/BUILD_GUIDE.md @@ -1,9 +1,9 @@ # Build Guide -## Platform-specific setup +## Build Environment Setup ### Windows - +What these instructions look like depends on whether NoahAndrews's setup scripts get merged ### Mac -- cgit v1.2.3-24-g4f1b From 0eb252eb61b1ec21131f8b3bd4048ff5c434f921 Mon Sep 17 00:00:00 2001 From: Noah Andrews Date: Wed, 2 Mar 2016 22:16:43 -0500 Subject: Added Mac section (copy/pasted from PCB_GUIDE.md) --- BUILD_GUIDE.md | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'BUILD_GUIDE.md') diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md index d7106d918..07ed0e98d 100644 --- a/BUILD_GUIDE.md +++ b/BUILD_GUIDE.md @@ -6,7 +6,17 @@ What these instructions look like depends on whether NoahAndrews's setup scripts get merged ### Mac +If you're using homebrew, you can use the following commands: + brew tap osx-cross/avr + brew install avr-libc + brew install dfu-programmer + +Otherwise, these instructions will work: + +1. Install Xcode from the App Store. +2. Install the Command Line Tools from `Xcode->Preferences->Downloads`. +3. Install [DFU-Programmer][dfu-prog]. ### Linux -- cgit v1.2.3-24-g4f1b From b9c22ff8fc0e27b1bcc4f62785289ca2c7e695d9 Mon Sep 17 00:00:00 2001 From: Noah Andrews Date: Wed, 2 Mar 2016 22:38:22 -0500 Subject: Clarified recommended Mac setup method --- BUILD_GUIDE.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'BUILD_GUIDE.md') diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md index 07ed0e98d..783d00e8d 100644 --- a/BUILD_GUIDE.md +++ b/BUILD_GUIDE.md @@ -6,13 +6,15 @@ What these instructions look like depends on whether NoahAndrews's setup scripts get merged ### Mac -If you're using homebrew, you can use the following commands: +If you're using [homebrew,](http://brew.sh/) you can use the following commands: brew tap osx-cross/avr brew install avr-libc brew install dfu-programmer -Otherwise, these instructions will work: +This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. + +You can also try these instructions: 1. Install Xcode from the App Store. 2. Install the Command Line Tools from `Xcode->Preferences->Downloads`. -- cgit v1.2.3-24-g4f1b From fe7738f2df82db2995857b0fd9e3a965dc3b0d6a Mon Sep 17 00:00:00 2001 From: Noah Andrews Date: Fri, 4 Mar 2016 21:51:09 -0500 Subject: Added Windows and Linux instructions to BUILD_GUIDE.md --- BUILD_GUIDE.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'BUILD_GUIDE.md') diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md index 783d00e8d..4ff25479d 100644 --- a/BUILD_GUIDE.md +++ b/BUILD_GUIDE.md @@ -3,7 +3,11 @@ ## Build Environment Setup ### Windows -What these instructions look like depends on whether NoahAndrews's setup scripts get merged +1. Install [MHV AVR Tools](https://infernoembedded.com/sites/default/files/project/MHV_AVR_Tools_20131101.exe). Disable smatch, but **be sure to leave the option to add the tools to the PATH checked**. +2. Install [MinGW](https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download). During installation, uncheck the option to install a graphical user interface. **DO NOT change the default installation folder.** The scripts depend on the default location. +3. Clone this repository. [This link will download it as a zip file, which you'll need to extract.](https://github.com/jackhumbert/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer. +4. Right-click on the 1-setup-path-win batch script, select "Run as administrator", and accept the User Account Control prompt. Press the spacebar to dismiss the success message in the command prompt that pops up. +5. Right-click on the 2-setup-environment-win batch script, select "Run as administrator", and accept the User Account Control prompt. This part may take a couple of minutes, and you'll need to approve a driver installation, but once it finishes, your environment is complete! ### Mac If you're using [homebrew,](http://brew.sh/) you can use the following commands: @@ -21,6 +25,12 @@ You can also try these instructions: 3. Install [DFU-Programmer][dfu-prog]. ### Linux +Install AVR GCC and dfu-progammer with your favorite package manager. + +Debian/Ubuntu example: + + sudo apt-get update + sudo apt-get install gcc-avr dfu-programmer ### 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 file](VAGRANT_GUIDE.md). \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 553668550b6d3790639b2671e89ef0e34869dbbf Mon Sep 17 00:00:00 2001 From: Noah Andrews Date: Fri, 4 Mar 2016 23:21:29 -0500 Subject: Added build instructions to BUILD_GUIDE.md --- BUILD_GUIDE.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) (limited to 'BUILD_GUIDE.md') diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md index 4ff25479d..81c3ec44f 100644 --- a/BUILD_GUIDE.md +++ b/BUILD_GUIDE.md @@ -33,4 +33,23 @@ Debian/Ubuntu example: sudo apt-get install gcc-avr dfu-programmer ### 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 file](VAGRANT_GUIDE.md). \ No newline at end of file +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 file](VAGRANT_GUIDE.md). + +## Verify Your Installation +1. If you haven't already, obtain this repository ([https://github.com/jackhumbert/qmk_firmware](https://github.com/jackhumbert/qmk_firmware)). You can either download it as a zip file and extract it, or clone it using the command line tool git or the Github Desktop application. +2. Open up a terminal or command prompt and navigate to the qmk_firmware folder using the `cd` command. The command prompt will typically open to your home directory. If, for example, you cloned the repository to your Documents folder, then you would type `cd Documents/qmk_firmware`. If you extracted the file from a zip, then it may be named `qmk_firmware-master` instead. +3. To confirm that you're in the correct location, you can display the contents of your current folder using the `dir` command on Windows, or the `ls` command on Linux or Mac. You should see several files, including `README.md` and a `quantum` folder. From here, you need to navigate to the appropriate folder under `keyboard/`. For example, if you're building for a Planck, run `cd keyboard/planck`. +4. Once you're in the correct keyboard-specific folder, run the `make` command. This should output a lot of information about the build process. + +## Customizing, Building, and Deploying Your Firmware +1. Running the `make` command from your keyboard's folder will generate a .hex file based on the default keymap. All keymaps for a particular keyboard live in the `keymaps` folder in that keyboard's folder. To create your own keymap, copy `keymaps/default/keymap.c` to the `keymaps` folder, and rename it with your name, for example jack.c. Or, if you don't care about the ability to share your keymap with the community via GitHub, you can just modify the default keymap itself. Details on how to program keymap files can be found in other guides. +2. To build a keymap other than the default, type `KEYMAP=` after `make`. So if I've named my keymap jack.c, the full command would be `make KEYMAP=jack`. +3. How you deploy the firmware will depend on whether you are using a PCB or a Teensy. In both cases, you'll need to put the keyboard in bootloader mode, either by pressing a button on the PCB/Teensy or pressing the key with the `RESET` keycode. Then, if you're using a PCB, just run `make KEYMAP= dfu` to both build and deploy the firmware. If you're using a Teensy, you'll probably need to take the .hex file that make produces in the keyboard's folder, and deploy it using the [Teensy Loader.](https://www.pjrc.com/teensy/loader.html) + +## Helpful Tips +1. On Linux or OS X, you can run `sleep 5; make KEYMAP= dfu` to delay building/deploying the firmware until for 5 seconds, giving you a chance to put the firmware into bootloader mode. You can change the 5 to any number of seconds. + +## Troubleshooting +1. Try running `make clean` if the make command fails. + + WIP \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 1fd9dbdbe9e7a819a7dae50d9b745640435e0e13 Mon Sep 17 00:00:00 2001 From: Andrew Pritchard Date: Mon, 28 Mar 2016 08:39:39 -0700 Subject: Add avr-libc to the Debian build dependencies. Without avr-libc the build fails trying to #include_next a header from the standard library, which of course doesn't exist. --- BUILD_GUIDE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'BUILD_GUIDE.md') diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md index 81c3ec44f..e8b242e4e 100644 --- a/BUILD_GUIDE.md +++ b/BUILD_GUIDE.md @@ -25,12 +25,12 @@ You can also try these instructions: 3. Install [DFU-Programmer][dfu-prog]. ### Linux -Install AVR GCC and dfu-progammer with your favorite package manager. +Install AVR GCC, AVR libc, and dfu-progammer with your favorite package manager. Debian/Ubuntu example: sudo apt-get update - sudo apt-get install gcc-avr dfu-programmer + sudo apt-get install gcc-avr avr-libc dfu-programmer ### 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 file](VAGRANT_GUIDE.md). @@ -52,4 +52,4 @@ If you have any problems building the firmware, you can try using a tool called ## Troubleshooting 1. Try running `make clean` if the make command fails. - WIP \ No newline at end of file + WIP -- cgit v1.2.3-24-g4f1b From 60570f3e37c27e7583ccab862bbd88f8f38f1d8c Mon Sep 17 00:00:00 2001 From: Noah Andrews Date: Mon, 28 Mar 2016 22:02:52 -0400 Subject: Added clarifying steps to Windows section of build guide --- BUILD_GUIDE.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'BUILD_GUIDE.md') diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md index e8b242e4e..22df53c30 100644 --- a/BUILD_GUIDE.md +++ b/BUILD_GUIDE.md @@ -3,11 +3,13 @@ ## Build Environment Setup ### Windows -1. Install [MHV AVR Tools](https://infernoembedded.com/sites/default/files/project/MHV_AVR_Tools_20131101.exe). Disable smatch, but **be sure to leave the option to add the tools to the PATH checked**. -2. Install [MinGW](https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download). During installation, uncheck the option to install a graphical user interface. **DO NOT change the default installation folder.** The scripts depend on the default location. -3. Clone this repository. [This link will download it as a zip file, which you'll need to extract.](https://github.com/jackhumbert/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer. -4. Right-click on the 1-setup-path-win batch script, select "Run as administrator", and accept the User Account Control prompt. Press the spacebar to dismiss the success message in the command prompt that pops up. -5. Right-click on the 2-setup-environment-win batch script, select "Run as administrator", and accept the User Account Control prompt. This part may take a couple of minutes, and you'll need to approve a driver installation, but once it finishes, your environment is complete! +1. If you have ever installed WinAVR, uninstall it. +2. Install [MHV AVR Tools](https://infernoembedded.com/sites/default/files/project/MHV_AVR_Tools_20131101.exe). Disable smatch, but **be sure to leave the option to add the tools to the PATH checked**. +3. Install [MinGW](https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download). During installation, uncheck the option to install a graphical user interface. **DO NOT change the default installation folder.** The scripts depend on the default location. +4. Clone this repository. [This link will download it as a zip file, which you'll need to extract.](https://github.com/jackhumbert/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer. +5. Right-click on the 1-setup-path-win batch script, select "Run as administrator", and accept the User Account Control prompt. Press the spacebar to dismiss the success message in the command prompt that pops up. +6. Right-click on the 2-setup-environment-win batch script, select "Run as administrator", and accept the User Account Control prompt. This part may take a couple of minutes, and you'll need to approve a driver installation, but once it finishes, your environment is complete! +7. Future build commands should be run from the standard Windows command prompt, which you can find by searching for "command prompt" from the start menu or start screen. Ignore the "MHV AVR Shell". ### Mac If you're using [homebrew,](http://brew.sh/) you can use the following commands: -- cgit v1.2.3-24-g4f1b