break out a separate building documention for AltOS, and document the

process of building a Cortex toolchain there

diff --git a/AltOS/building.mdwn b/AltOS/building.mdwn
new file mode 100644 (file)
index 0000000..8328995
--- /dev/null
+++ b/AltOS/building.mdwn
@@ -0,0 +1,66 @@
+# Building AltOS
+
+The AltOS source tree has a fairly long list of build dependencies, because
+it builds firmware for at least 4 different processor cores, ground station 
+software in Java, various utilities in C, etc.  By *far* the easiest way to
+build from source is to start with a [Debian](http://debian.org) 'unstable' 
+installation and take advantage of Debian tools and processes.  From this
+platform, it is possible to build installable packages not only for Debian,
+but also for Windows, Mac OS X, and generic Linux.
+
+## Compilers
+
+We use standard gcc and OpenJDK to build all of the ground software, but the
+situation for building the firmware is a bit more complicated.  Because we
+realize many people may be only interested in working on the ground station
+software, or may only care about building firmware for a single target, we
+have crafted the Makefile contents to test for the presence of the various
+compilers... and will only build firmware for the targets we can find the
+right tools for!
+
+### cc1111
+
+The first generation of Altus Metrum products were all based on the TI cc1111,
+which has an 8051 core.  We started out using standard SDCC, but Keith made a
+number of changes to better support the cc1111, and then SDCC 3.X changed code
+generation such that 8051 executables became significantly larger and our code
+just wouldn't fit in available flash any more!  
+
+As a result, we maintain a fork of SDCC we call 'cc1111' that is based
+on the last upstream version of SDCC 2.X, plus a highly modified sdcdb with
+support for the cc1111 debugging interface.  This is avilable as a package in
+Debian, or you can find the sources on [git.gag.com](http://git.gag.com)
+in the project [debian/cc1111](http://git.gag.com/?p=debian/cc1111;a=summary).
+
+### AVR
+
+We use the standard gcc-avr tools for this target, which thanks to the 
+popularity of the [Arduino](http://arduino.cc) community are well taken care 
+of in Debian.
+
+### ARM Cortex
+
+Most of the new products we're working on now are based on system on chip
+parts using ARM Cortex M3 or ARM Cortex M0 cores.  These require a "bare metal"
+toolchain, not the standard ARM compiler and libraries used for ARM Linux.  We
+continue to discuss our needs with others in the Debian community and have
+high hopes for a suitable toolchain to eventually be part of the main 
+distribution.  But, in the meantime, here's what it takes to build a suitable
+toolchain in /opt/cortex:
+
+* mkdir /opt/cortex, and ensure it's owned by you (so no root privs are needed)
+* clone our [cortex-toolchain](http://git.gag.com/?p=fw/cortex-toolchain;a=summary) with `git clone git://git.gag.com/fw/cortex-toolchain`
+* cd into the cortex-toolchain directory, review the list of build dependencies
+  documented in the README file, then build using 
+  `./summon-arm-toolchain`.  This will download all
+  the source packages, unpack them, build everything, and install it all in
+  /opt/cortex automatically.  This takes a bunch of disk space and a lot of
+  time, so be patient!
+* clone our [pdclib](http://git.gag.com/?p=fw/pdclib;a=summary) C library
+  repository with `git clone git://git.gag.com/fw/pdclib`
+* cd into the pdclib directory, and build using `make ; make install` which
+  will build the library using the just-installed cortex tools and deliver
+  the results to the /opt/cortex tree
+
+That's it!  You should now have an ARM toolchain targetting bare metal for
+both Cortex M0 and M3 variants including a minimal C runtime library.

diff --git a/AltOS/index.mdwn b/AltOS/index.mdwn
index 156e02be93d50354807238792ee67ea9f6ba5a2f..745e53da32dcae02cc01c155a7bdde30efdf4605 100644 (file)
--- a/AltOS/index.mdwn
+++ b/AltOS/index.mdwn
@@ -41,14 +41,7 @@ The latest source, which may include unreleased work in progress, is always
 available from [git.gag.com](http://git.gag.com) 
 in the project [fw/altos](http://git.gag.com/?p=fw/altos;a=summary).  
 
-If you need to debug code on an Altus Metrum product, or want to do custom
-development, you need a 2.X version of SDCC.  Version 3.X adds features that 
-bloat the code generated on 8051 enough to overflow the available flash memory
-size.  As a result, we maintain a fork of SDCC we call 'cc1111' that is based
-on the last upstream version of SDCC 2.X, plus a highly modified sdcdb with 
-support for the cc1111 debugging interface.  This is avilable as a package in
-Debian, or you can find the sources on [git.gag.com](http://git.gag.com) 
-in the project [debian/cc1111](http://git.gag.com/?p=debian/cc1111;a=summary). 
+We've gathered a few notes on [buidling AltOS](building).
 
 ## Future Plans ##