Building and installing FreeCalypso host tools
==============================================

In order to compile and install our host tools, just run 'make', then
'make install' as root.

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.  This toolchain is used to compile target-utils in
this package as well as our separately-maintained Citrine firmware.  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
target-utils or Citrine.

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.