Cygwin Based Users Guidev0.2 -formatting revisions

1 files changed, 47 insertions, 47 deletions

diff --git a/keyboard/planck/CYGWIN_GUIDE.md b/keyboard/planck/CYGWIN_GUIDE.md
index 896a42c76..2fa4452f1 100755
--- a/keyboard/planck/CYGWIN_GUIDE.md
+++ b/keyboard/planck/CYGWIN_GUIDE.md
@@ -1,41 +1,41 @@
-#Planck Advanced (but not too advanced) Cygwin Users Guide

-If you are a user of the [Cygwin environment](https://cygwin.com) in Windows and want the freedom to use the latest tools available, then this is the guide for you. If compiling your own copy of the latest and greatest Gnu C compiler makes you super happy, then this is the guide for you. If the command line make you smile, then this is the guide for you.

+#Planck Advanced (but not too advanced) `cygwin` Users Guide

+If you are a user of the [cygwin environment](https://cygwin.com) in Windows and want the freedom to use the latest tools available, then this is the guide for you. If compiling your own copy of the latest and greatest Gnu C Compiler makes you super happy, then this is the guide for you. If the command line make you smile, then this is the guide for you.

 

 

-This guide was written step by step as I went through the process on a Windows10 x86_64 based system.  This should be generally applicable to to any Windows Environment with Cygwin.

+This guide was written step by step as I went through the process on a `Windows 10` `x86_64` based system.  This should be generally applicable to to any `Windows` environment with `cygwin`.

 

 

 #####Do not skip steps. Do not move past a step until the previous step finishes successfully.

 

 

 

-based on [avr-libc installation guide](http://www.nongnu.org/avr-libc/user-manual/install_tools.html)

+Based on [avr-libc installation guide](http://www.nongnu.org/avr-libc/user-manual/install_tools.html)

 

 

-###get the required packages

-Download the Cygwin Installer ([x86_64](https://cygwin.com/setup-x86_64.exe) or [x86_32](https://cygwin.com/setup-x86.exe)) and install the default system plus the following if they are not already selected:

--devel/gcc-core

--devel/gcc-g++

--devel/flex

--devel/git

--libs/libglib2.0_0

--libs/libgcc1

--interpreters/m4

--web/wget

+##Get the Required Packages

+Download the `cygwin` setup ([x86_64](https://cygwin.com/setup-x86_64.exe)) and install the default system plus the following if they are not already selected:

+- devel/gcc-core

+- devel/gcc-g++

+- devel/flex

+- devel/git

+- libs/libglib2.0_0

+- libs/libgcc1

+- interpreters/m4

+- web/wget

 

 The following sources will be required:

--get [gmp](https://gmplib.org/) (6.1.0)

--get [mpfr](http://www.mpfr.org/) (3.1.3)

--get [mpc](http://www.multiprecision.org/) (1.0.3) 

--get [binutils](https://www.sourceware.org/binutils/) (2.26)

--get [gcc](https://gcc.gnu.org/) (5.3.0)

--get [avr-libc](http://www.nongnu.org/avr-libc/) (2.0.0)

+- [gmp](https://gmplib.org/) (6.1.0)

+- [mpfr](http://www.mpfr.org/) (3.1.3)

+- [mpc](http://www.multiprecision.org/) (1.0.3) 

+- [binutils](https://www.sourceware.org/binutils/) (2.26)

+- [gcc](https://gcc.gnu.org/) (5.3.0)

+- [avr-libc](http://www.nongnu.org/avr-libc/) (2.0.0)

 

 The `dfu-programmer` will be required to flash the new firmware 

--get [dfu-programmer](https://dfu-programmer.github.io/) (0.7.2)

+- [dfu-programmer](https://dfu-programmer.github.io/) (0.7.2)

 

 

-The set of commands below will create a directory (`~/local/avr`) for the sources you compile to be installed on the machine and a directory (`~/src`) for these source files to be stored. The commands then download the sources of the needed packages and unpack them. note: the expand commands are different depending on if the packages are offered as a bz2 or gz archive

+The set of commands below will create a directory (`~/local/avr`) for the sources you compile to be installed on the machine and a directory (`~/src`) for these source files to be stored. The commands then download the sources of the needed packages and unpack them. Note: the expand commands are different depending on if the packages are offered as a `bz2` or `gz` archive

 

 ```

 $ mkdir ~/local/avr

@@ -55,8 +55,8 @@ $ tar -zxf gcc-5.3.0.tar.gz
 $ tar -xjf avr-libc-2.0.0.tar.bz2 

 ```

 

-###setup build environment

-These commands will set up the install directory and the PATH variable, which will allow you to access your installed packages.  note: if you close the cygwin terminal window, you will need to rerun these commands, they are not permanent 

+##Setup the Build Environment

+These commands will set up the install directory and the `PATH` variable, which will allow you to access your installed packages.  Note: if you close the `cygwin` terminal window, you will need to rerun these commands, they are not permanent.

 ```

 $ PREFIX=$HOME/local/avr

 $ export PREFIX

@@ -65,10 +65,10 @@ $ PATH=$PATH:$PREFIX/bin
 $ export PATH

 ```

 

-##The gcc required math library packages

-The following packages are required to be complied and installed in order to compile gcc.  They are not available through the cygwin package system, so we have to make them ourselves.  They must be complied in this order because each one depends on the previous.

+##The `gcc` Required Math Library Packages

+The following packages are required to be complied and installed in order to compile `gcc`.  They are not available through the `cygwin` package system, so we have to make them ourselves.  They must be complied in this order because each one depends on the previous.

 

-###build and install gmp

+###Build and Install `gmp`

 ```

 $ cd ~/src/gmp-6.1.0

 $ ./configure --enable-static --disable-shared

@@ -77,7 +77,7 @@ $ make check
 $ make install

 ```

 

-###build and install mpfr

+###Build and Install `mpfr`

 ```

 $ cd ~/src/mpfr-3.1.3

 $ ./configure --with-gmp-build=../gmp-6.1.0 --enable-static --disable-shared

@@ -86,7 +86,7 @@ $ make check
 $ make install

 ```

 

-###build and install mpc

+###Build and Install `mpc`

 ```

 $ cd ~/src/mpc-1.0.3

 $ ./configure --with-gmp=/usr/local --with-mpfr=/usr/local --enable-static --disable-shared

@@ -96,8 +96,8 @@ $ make install
 ```

 

 ##OPTIONAL Part

-You can build and install a brand new gcc or you can use the one supplied by cygwin.  This will take about 4-5 hours to compile (It is a "native build", so it does the entire build **3 times**. This takes a long while). I would skip it.

-###build and install gcc on your machine  

+You can build and install a brand new `gcc` or you can use the one supplied by `cygwin`.  This will take about 4-5 hours to compile (It is a "native build", so it does the entire build **3 times**. This takes a long while). I would skip it.

+###Build and Install `gcc` on your Machine  

 ```

 $ cd ~/src/gcc-5.3.0

 $ mkdir obj-local

@@ -107,7 +107,7 @@ $ make
 $ make install

 ```

 

-###build and install binutils on your machine

+###Build and Install `binutils` on your Machine

 ```

 $ cd ~/src/binutils-2.26

 $ mkdir obj-local

@@ -118,10 +118,10 @@ $ make install
 ```

 ##End OPTIONAL Part

 

-##Buliding binutils, gcc and avr-libc for the AVR system

-Now we can make the critical stuff for compiling our firmware, binutils, gcc, and avr-libc for the AVR architectures.  These allow us to build and manipulate the firmware for the Keyboard.

+##Buliding `binutils`, `gcc`, and `avr-libc` for the AVR system

+Now we can make the critical stuff for compiling our firmware: `binutils`, `gcc`, and `avr-libc` for the AVR architecture.  These allow us to build and manipulate the firmware for the keyboard.

 

-###build binutils for avr

+###Build `binutils` for AVR

 ```

 $ cd ~/src/binutils-2.26

 $ mkdir obj-avr

@@ -131,7 +131,7 @@ $ make
 $ make install

 ```

 

-###build gcc for avr

+###Build `gcc` for AVR

 ```

 $ cd ~/src/gcc-5.3.0

 $ mkdir obj-avr

@@ -141,9 +141,9 @@ $ make
 $ make install

 ```

 

-For building the avr-libc, we have to specify the host build system.  in my case it is `x86_64-unknown-cygwin`. You can look for build system type in the gcc configure notes for the proper `--build` specification to pass when you configure avr-libc

+For building the `avr-libc`, we have to specify the host build system.  in my case it is `x86_64-unknown-cygwin`. You can look for build system type in the `gcc` configure notes for the proper `--build` specification to pass when you configure `avr-libc`.

 

-###build avr-libc for avr

+###Build `avr-libc` for AVR

 ```

 $ cd ~/src/avr-libc-2.0.0

 $ ./configure --prefix=$PREFIX --build=x86_64-unknown-cygwin --host=avr

@@ -151,9 +151,9 @@ $ make
 $ make install

 ```

 

-##Install dfu-programmer

-To install the dfu-programmer, we must get if from [their website](https://dfu-programmer.github.io/) (no fancy command line tricks here, but [this](http://iweb.dl.sourceforge.net/project/dfu-programmer/dfu-programmer/0.7.2/dfu-programmer-win-0.7.2.zip) might work).

-Copy this file into your cygwin home directory.  (For me, it is `C:\cygwin64\home\Kevin`), extract the files, move `dfu-programmer.exe` to `~/local/avr/bin`. Most obnoxiously, the `libusb0_x86.dll` and `libusb0.sys` need to be moved from  `dfu/dfu-prog-usb-1.2.2/x86/` to a directory in the Windows PATH and the Cygwin PATH. I achieved this by moving the files in Windows Explorer to  `C:\cygwin64\home\Kevin\local\avr\bin` Then, in a WINDOWS command prompt running:

+##Install `dfu-programmer`

+To install the `dfu-programmer`, we must get if from [their website](https://dfu-programmer.github.io/) (no fancy command line tricks here, but [this](http://iweb.dl.sourceforge.net/project/dfu-programmer/dfu-programmer/0.7.2/dfu-programmer-win-0.7.2.zip) might work).

+Copy this file into your `cygwin` home directory.  (For me, it is `C:\cygwin64\home\Kevin`), extract the files, move `dfu-programmer.exe` to `~/local/avr/bin`. Most obnoxiously, the `libusb0_x86.dll` and `libusb0.sys` need to be moved from  `dfu/dfu-prog-usb-1.2.2/x86/` to a directory in the `Windows` `PATH` and the `cygwin` `PATH`. I achieved this by moving the files with Windows Explorer (you know, click and drag...) to  `C:\cygwin64\home\Kevin\local\avr\bin` Then, in a `WINDOWS` command prompt running:

 ```

 C:\> set PATH=%PATH%;C:\cygwin64\home\Kevin\local\avr\bin

 ```

@@ -169,11 +169,11 @@ Type 'dfu-programmer --help'    for a list of commands
      'dfu-programmer --targets' to list supported target devices

 ```

 If you are not getting the above result, you will not be able to flash the firmware! 

--Try making sure your PATH variables are set correctly for both windows and cygwin. 

--Do not try to extract it with cygwin's `unzip` as it does not set the executable permissions correctly.

+- Try making sure your `PATH` variables are set correctly for both `Windows` and `cygwin`. 

+- Do not extract it with `cygwin`'s `unzip` as it does not set the executable permissions correctly. If you did it anyway, do `chmod 755 dfu-programmer.exe`

 

 ####Install the USB drivers

-These drivers are included in the `dfu-programmer` 0.7.2 (but you can get newer ones [here](http://iweb.dl.sourceforge.net/project/libusb-win32/libusb-win32-releases/1.2.6.0/libusb-win32-bin-1.2.6.0.zip)) and allow the dfu to program the firmware. From an administrator-privileged Windows terminal, run the following command (adjust the path as necessary) and accept the prompt that pops up:

+These drivers are included in the `dfu-programmer` 0.7.2 (but you can get newer ones [here](http://iweb.dl.sourceforge.net/project/libusb-win32/libusb-win32-releases/1.2.6.0/libusb-win32-bin-1.2.6.0.zip)) and allow the `dfu-programmer` to program the firmware. From an **administrator-privileged** `Windows` terminal, run the following command (adjust the path as necessary) and accept the prompt that pops up:

 ```

 C:\> pnputil -i -a C:\cygwin64\home\Kevin\dfu-prog-usb-1.2.2\atmel_usb_dfu.inf

 ```

@@ -193,9 +193,9 @@ Number successfully imported: 1
 

 ##Building and Flashing the Planck firmware!

 

-If you did everything else right. This part should be a snap! Grab the latest sources from github, make the Plank firmware, then flash it.

+If you did everything else right. This part should be a snap! Grab the latest sources from `github`, make the Plank firmware, then flash it.

 

-###build Planck and load the firmware

+###Build Planck and Load the Firmware

 ```

 $ cd ~/src

 $ git clone https://github.com/jackhumbert/qmk_firmware.git

@@ -225,7 +225,7 @@ Size after:
 -------- end --------

 ```

 

-If you don't, you did not build the firmware, and you will have nothing to flash.  If you have the fresh clone from github, it was probably something in the install process, go check and see what didn't work and threw errors or what steps you might have missed.

+If you do not get the above, you **did not** build the firmware, and you will have nothing to flash.  If you have the fresh clone from github, it was probably something gone wrong in this install process, go check and see what didn't work and threw errors or what steps you might have missed.

 

 But if everything went OK, you are ready to flash! Press the reset button on the bottom of the Planck, wait two seconds, then:

 ```