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

Our FreeCalypso host tools are designed to be installed in the /opt/freecalypso
directory hierarchy on your system.  The author of this software is very
old-fashioned and refuses to use autotools (sorry, we aren't GNU), hence
various hard-coded paths under /opt/freecalypso are sprinkled in bazillion
places - thus changing this fixed install location is deemed to be impractical.

In order to compile and install our host tools, follow these steps:

1: Run 'make' as a regular user (not root) to compile the software.

2: Decide if you prefer to have the /opt/freecalypso directory and everything
   under it to be owned by root or by your non-root uid.

If you prefer /opt/freecalypso to be root-owned:

   3A: Run 'make install' as root; the install rule in the
       Makefile will do mkdir -p /opt/freecalypso as its first step.

   4A: You are done!

If you prefer /opt/freecalypso to be owned by your "regular" non-root uid:

   3B: Become root just to create the /opt/freecalypso directory and chown it
       to your non-root uid.

   4B: Run 'make install' as your regular uid; it should succeed because you
       should have made yourself the owner of /opt/freecalypso with full write
       permission in the previous step.

   5B: You are done!

The host tool binaries will be installed in /opt/freecalypso/bin; you can
either add this directory to your PATH or make symlinks from /usr/bin or
/usr/local/bin or wherever.

Dependencies
============

All FreeCalypso host tools are written in plain C, and with the exception of one
special hack-utility that has been excluded from the standard build set, 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
exception is the fc-lcdemu hack which needs libX11 to compile and an X11 display
to run.  It was a developer-only hack-utility to begin with, and the developer
setup of which it was a part never worked in a satisfactory manner, so it has
been retired.  If you would like to play with it, you will need to compile it
separately, as it has been excluded from the top Makefile in order to have the
standard build set with no dependencies.

The previous dependency on OpenSSL libraries for DES decryption of the factory
IMEI record on the Pirelli DP-L10 has been eliminated by incorporating our own
simple DES implementation (performance is not a concern for the one time
operation of retrieving the factory IMEI) into our rvinterf/etmsync source, and
the functions that require access to Pirelli's IMEI have now been integrated
into fc-fsio.

libserial and Linux specifics
=============================

We have our own private library called libserial which contains our serial port
handling code (serial ports are what we use to talk to Calypso GSM devices),
and this library exists in several different versions.  At the top level of our
source tree libserial is a symlink to one of libserial-* versions.

Starting with fc-host-tools-r7, the default version of libserial (i.e., the
version to which the libserial symlink points in the official release source)
is libserial-newlnx.  This version of libserial has the advantage of supporting
high GSM baud rates (see doc/High-speed-serial) with FTDI adapters without
needing a dirty patch to the in-kernel driver, but it comes at the price of
being very specific to Linux.  If you would like to run FreeCalypso host tools
under FreeBSD, illumos or some other alternative-to-Linux OS, see the section
titled "Support for other Unix flavors" in the doc/High-speed-serial article.

Target binaries
===============

If you are installing a packaged release of FreeCalypso host tools, there will
be a number of prebuilt target binaries (code to be run on the Calypso ARM7
processor) in the target-bin directory; when you run make install as instructed
above, these target binaries will be installed in /opt/freecalypso/target-bin.
Otherwise, you will need to compile them yourself using an ARM7 toolchain as
detailed below.

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 several target binaries being built, including compalstage
and loadagent which are needed in order to use FreeCalypso loadtools.  Run
'make install' to install these target binaries in /opt/freecalypso/target-bin,
which is where loadtools will look for them.

Run 'make all' in target-utils to build some additional target code pieces that
are needed only for development and only very rarely.