--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/INSTALL	Wed Oct 26 07:48:29 2016 +0000
@@ -0,0 +1,95 @@
+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:
+
+   3A: Become root just to create the /opt/freecalypso directory and chown it
+       to your non-root uid.
+
+   4A: 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.
+
+   5A: 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.
+
+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.