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.