--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Compiling	Sat Jun 11 00:13:35 2016 +0000
@@ -0,0 +1,140 @@
+There are 3 parts to the complete FreeCalypso software suite which are built
+independently of each other:
+
+* The tools that run on a GNU/Linux PC or other host system are the most
+  straightforward: there is a top level Makefile (named Makefile.hosttools if
+  you looking at a development source snapshot, will be renamed to just
+  Makefile in packaged releases of the host tools) that coordinates building
+  and installing all of them.
+
+* The gsm-fw tree, which will eventually become our main GSM firmware, needs to
+  be built with a GNU cross-compiler toolchain for ARM7.  This firmware can be
+  built for several different target devices and with different feature
+  configurations, hence there is no singular build for it - it's more like the
+  Linux kernel in terms of its build configuration management.
+
+* We also have a few utilities which need to be compiled to run on Calypso
+  targets, but which are not part of gsm-fw; they are gathered in the
+  target-utils tree.  They are built with the same GNU toolchain for ARM7 as
+  gsm-fw, but don't have any fancy configuration system.
+
+Building and installing FreeCalypso host tools
+==============================================
+
+If you are working with a packaged FC host tools release, just run 'make', then
+'make install' as root.  If you are working with a development source snapshot,
+do 'make -f Makefile.hosttools' instead.
+
+The "standard" install directories are /usr/local/bin for binaries and
+/usr/local/share/freecalypso for helper files.  If you need to change these
+paths to something else, you'll need to edit a bunch of individual component
+Makefiles, and possibly also some source files like loadtools/defpath.c -
+sorry, FreeCalypso is not GNU and does not use autotools.
+
+All FreeCalypso host tools are written in plain C, and with the exception of a
+few utilities in the "special-purpose hacks" category, they have absolutely no
+library dependencies beyond libc.  In other words, they are very friendly to
+those who like bare bones minimalist systems.  The only exceptions are
+fc-getpirimei and fc-pirhackinit which use libcrypto from OpenSSL for DES
+functions, and fc-lcdemu which needs libX11 to compile and an X11 display to
+run.  But as you can read in Host-tools-overview, these utilities are not
+particularly important, so if your system lacks those libraries, just edit the
+Makefiles to not build these utilities - it is very unlikely that you will miss
+them.
+
+To those who are going to build distro packages from these fc-host-tools: it
+is recommended that you leave fc-getpirimei, fc-pirhackinit and fc-lcdemu out
+of the basic package - please don't create extra dependencies just to support a
+few odd hacks which are unlikely to ever be used by anyone other than the
+developer who needed them at one time and no longer even uses them herself as
+their original one-time purpose has already been served.
+
+Building and installing the ARM7 toolchain
+==========================================
+
+The current "official" GNU ARM toolchain for FreeCalypso consists of
+binutils-2.21.1, gcc-4.5.4 and newlib-2.0.0 with a specific set of patches and
+build configuration options.  Build it as follows:
+
+1. Download these 3 source tarballs for the standard GNU+newlib components:
+
+   binutils-2.21.1a.tar.bz2
+   gcc-core-4.5.4.tar.bz2
+   newlib-2.0.0.tar.gz
+
+2. Run the build+install.sh script in the toolchain directory.  Read the
+   comments in the script first for the usage instructions.
+
+The toolchain thus built will need to be in your PATH before you can compile
+gsm-fw or target-utils.
+
+Please note: the toolchain that is prescribed for FreeCalypso as above is
+*believed* to be equivalent to the one used by OsmocomBB, but there are no
+guarantees.  Use any other toolchain at your own risk.
+
+Compiling target-utils
+======================
+
+Running 'make' in the target-utils tree with the ARM7 toolchain present in your
+PATH will result in compalstage and loadagent being built; these are the two
+components needed in order to use FreeCalypso loadtools.  Run 'make install' to
+install these target binaries in /usr/local/share/freecalypso, which is where
+loadtools will look for them.
+
+Run 'make all' in target-utils to build some other components that aren't
+really needed.
+
+Compiling FreeCalypso GSM firmware
+==================================
+
+The firmware in our gsm-fw tree can be built in many different configurations,
+hence there is no singular build for it.  The configuration choices consist of:
+
+* Which target device the firmware should be built for: the target device
+  selection is made at compile time; do not attempt to take a firmware image
+  built for one target device and flash or fc-xram it into another!
+
+* What functionality is to be included.  As the FreeCalypso firmware subproject
+  moves forward, we gradually add chunks of functionality, slowly approaching
+  what each target device is ultimately capable of.  However, each time we add
+  a new piece of functionality, the ability to build a firmware image that works
+  like before, without the newly added functionality, still remains.  Each
+  feature to be included needs to be explicitly selected.
+
+* Miscellaneous configuration: which Calypso UART should be used for what,
+  should the firmware use a real FFS (flash file system) in flash or a fake one
+  in RAM, etc.
+
+The GSM firmware build configuration is set by way of an editable text file
+named build.conf; the configuration and build procedure is as follows:
+
+1. Look at the available repertoire of standard configurations under
+   gsm-fw/configs and choose which one you would like to use, either as-is or
+   as a basis for your own;
+
+2. Copy the configuration you selected to build.conf in the gsm-fw directory;
+
+3. Optionally edit it to taste - the configuration language is Bourne shell;
+
+4. Run 'make' in the gsm-fw directory.
+
+Depending on the configuration, either a flashable or a RAM-loadable image will
+be built by default.  A flashable image will appear in finlink/flashImage.bin;
+these images are meant to be programmed with fc-loadtool's flash program-bin
+command; the starting flash address at which the image needs to be programmed
+depends on the target device - see target-specific notes.  A RAM-loadable image
+will appear in finlink/ramImage.srec; these images are meant to be loaded and
+run with the fc-xram utility.
+
+It is possible to build either a flashable or a RAM-loadable image, or both,
+without changing build.conf: run 'make flashImage' or 'make ramImage' as
+desired.  (The compilation of each module from source into a .o and all
+intermediate linking steps are agnostic to whether a flashImage or a ramImage
+is being built, only the very final link step differs.)  Any otherwise working
+configuration can be built into a flashImage, even if it makes no logical sense
+to do so, but the ability to build a ramImage for a given configuration depends
+on the code image size (which in turn depends on the selected feature set) and
+the amount of RAM available on the target in question: most Calypso GSM devices
+have small RAM, enough to satisfy a GSM firmware's data space requirements, but
+not enough to hold the entire firmware code in RAM as well.  Please see target-
+specific notes for more details.