+
−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.
+
−See PACKAGING and doc/opt-freecalypso-tree for more notes on this subject.
+
−
+
−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.
+
−
+
−CC= and CFLAGS= selection
+
−=========================
+
−
+
−Our Makefile hierarchy is set up to build with CC=gcc and CFLAGS=-O2 by default.
+
−If you need to change either or both of these selections, you can do it by
+
−adding CC= and/or CFLAGS= on the make invokation line, for example:
+
−
+
−make CC=mygcc CFLAGS="-g -O2 -whatever-options"
+
−
+
−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-linux.  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 experimental FC Selenite
+
−firmware.  (Our production firmwares are currently built with TI's TMS470
+
−toolchain instead.)  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 FC Selenite.  The officially recommended install location for
+
−this toolchain is /opt/freecalypso/gcc.
+
−
+
−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.
+
−
+
−Staged installs
+
−===============
+
−
+
−As already explained above, our FC host tools need to be installed under
+
−/opt/freecalypso on your system in order to function correctly, and this runtime
+
−location is not changeable.  However, some users have requested an ability to
+
−do a staged install: have the 'make install' operation install the finished
+
−tree of files in some staging location, with the expectation that it will be
+
−subsequently moved to /opt/freecalypso by some other mechanism.  One use case
+
−that has been presented to us was automated building of binary distribution
+
−packages on a build host where writing to /opt/freecalypso is not allowed.
+
−
+
−If you need to make a staged install of this sort, you can do it like this:
+
−
+
−make install INSTALL_PREFIX=/home/me/my-fc-staging-area
+
−
+
−Please note that this INSTALL_PREFIX= scheme changes *only* the location where
+
−'make install' will deposit the installable files; it does NOT change the
+
−location where our programs will look for other programs and helper files: the
+
−latter location is hard-coded as /opt/freecalypso is bazillion places throughout
+
−our code base.