+
−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 have absolutely no
+
−library dependencies beyond libc.  In other words, they are very friendly to
+
−those who like bare bones minimalist systems.
+
−
+
−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.
+
−
+
−Previous versions of this FC host tools package included a UI development aid
+
−utility called fc-lcdemu which needs libX11 to compile and an X11 display to
+
−run; this utility has now been moved to a separate freecalypso-ui-dev
+
−repository and is no longer a part of the core FC host tools package.
+
−
+
−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.