Add content about compile options, about boards.txt

AddingOptibootChipsToIde.md

@@ -2,4 +2,17 @@
 
 This involves adding or editing a "boards.txt" file somewhere in the Arduino application or user sketch directory hierarchy.
 
-Both the preferred location, and the format, of the file change from version to version of the IDE.
+Both the preferred location and the format of the file change from version to version of the IDE.
+
+# IDE Version 1.6.4 (and later)
+Verions 1.5.x (beta) of the IDE added support for a much broader range of non-AVR and 3rd party hardware.  This changed the directory structure in the user's sketchbook folder in ways that were incompatible with 1.0.x (in particular, adding a "platform" sub directory, so that boards.txt was in <sketchbook>/hardware/<extname>/<platformname>/)
+
+In 1.6.4 (a production release), the IDE added a "boards manager" that permits a 3rd party extension to be automatically downloaded and installed simply by adding a URL in the preferences panel and (in yet another location and clicking an "Install" button in the Boards Manager panel.  (The actual files end up in yet a different place in the file system, but this should be transparent to the users.)  This is the preferred way to install the Optiboot boards.txt if you are running 1.6.4 or later, but it does not (currently) install source code.
+
+# IDE version 1.0.x
+In version 1.0 of the Arduino IDE, it became possible to put hardware extensions in the sketchbook folder, by putting new subdirectories in <sketchbook>/hardware/<extname>.  You could put a suitably formatted boards.txt there describing the new optiboot cpus, pointing toward .hex files located in that tree, or in other locations.
+
+
+# IDE Version 00xx
+Optiboot was written prior to version 1.0 of the IDE.  In those days, the only way to add additional boards was to modify the boards.txt file that included within the directory structure of the IDE itself. (<installDir>/hardware/arduino/boards.txt, with the .hex files in <installDir>/hardware/arduino/bootloaders/optiboot)  The directory structure of the Optiboot repositor reflects this old structure.
+

CompilingOptiboot.md

@@ -13,4 +13,35 @@ In all cases, Optiboot compiles directly from the command line using "make", rat
 
   * Local Development Environment - you have WinAVR (on Windows), CrossPack (on Mac), or an avr-gcc package (linux) installed on your system, with appropriate development tools somewhere in your path.
   * You have Arduino installed, and are trying to compile Optiboot from its home directory within the Arduino directory structure (hardware/arduino/bootloaders/optiboot/)  The Arduino app includes a pretty complete set of compiler tools, and these can be used to compile optiboot without installing a separate toolchain.
-  * You have downloaded the Arduino Source code, which also includes (binary) copies of avr-gcc toolchains, and a source directory containing the Optiboot source code.
+  * You have downloaded the Arduino Source code, which also includes (binary) copies of avr-gcc toolchains, and a source directory containing the Optiboot source code.
+
+
+# Compile Options #
+
+The Optiboot build procedure has been set up to allow a large set of customization options.  The general format of a build command is:
+
+~~~~
+make <options> <platform>
+~~~~
+Where <platform> is one of the named chips or boards implemented as normal targets in the makefile (ie "atmega328".) (the order may be reversed.) The implemented <options> include:
+
+  * AVR_FREQ=nnnnnn  --  Use CPU frequency as specified (default: target dependent, but usually 16000000L)
+  * BAUD_RATE=nnnnn  --  Use an alternate bitrate (default: usually 115200)
+  * LED\_START\_FLASHES=n  -- number of flashes to emit when the bootloader executes (default 3)
+  * BIGBOOT -- include extra features that cause the bootloader to grow to between 512 and 1024 bytes.
+  * SOFT_UART  --  use a bit-banged Software Uart.  Required for chips without a HW UART.
+  * LED\_DATA\_FLASH  -- flash the LED in the data receive function as well as at bootloader startup.
+  * LED=\<portpin\>  --  Like "LED=B5" or "LED=L5"
+  * SINGLESPEED
+  * UART=n  -- user UARTn instead of UART0.
+
+For example:
+
+~~~~
+make UART=1 LED=A7 AVR_FREQ=20000000L atmega1284
+~~~~
+Note that many of the board-level targets are implemented using a recursive invocation of make using this options.  For exmaple, the "pro20" target ends up being:
+
+~~~~
+ make atmega168 AVR_FREQ=20000000L LED_START_FLASHES=3
+~~~~