Installation location
=====================

The present FC SIM tools package is part of the greater FreeCalypso software
family, therefore, these tools are designed to be installed in the
/opt/freecalypso directory hierarchy on your system.  Changing this install
location is NOT ALLOWED: if you try to change it, you will break things, and I,
the author of this software, will not provide any help or support whatsoever to
anyone who seeks to change our fixed installation location.

Building and installing FC SIM tools
====================================

In order to compile and install our 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!

fc-simtool and other 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.

Including or excluding pcsc back end
====================================

The main body of software in the present package (fc-simtool, fc-uicc-tool and
all accessory programs except pcsc-specific ones) has zero compile-time
dependencies, needing only a working C compiler, standard system header files
under /usr/include, and libc.  However, one of the 3 card access back ends
supported by our tools is pcsc, and that back end requires libpcsclite and its
header files in order to compile.

You can include or exclude this pcsc back end depending on your needs.  If you
wish to use a professional card reading/programming station like HID Omnikey
3121 or its pocket sibling Omnikey 6121 (both of which are USB CCIDs), then you
will need to go through the pain of getting pcsc-lite up and running on your
system, including a working installation of libpcsclite and its header files -
going through this pcsc-lite software stack is the only way to operate these
USB CCIDs.  OTOH, if you are going to be a more casual (not professional) user
of FC SIM tools, only needing to occasionally poke at a SIM card inside your
Calypso phone or perhaps in a serial SIM reader, without ever using professional
card readers of the type that require pcsc-lite, then you can simply exclude the
part of our software suite that needs pcsc-lite (the pcsc back end), and enjoy
traditional FreeCalypso software with zero compile-time dependencies.

To exclude pcsc from your build, change the standard 'make' and 'make install'
commands as follows:

make PCSC=
make PCSC= install

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"

Porting to systems other than Linux
===================================

Most of the present software is written to be generic to any Unix, but the
Mother currently uses only Linux, thus no other systems have been tested.  One
component that is known to be Linux-specific is the serial SIM reader back end,
which is written to work with arbitrary UART baud rates and not just RS-232
standard ones like 9600 bps - see doc/Serial-SIM-readers for the details.

Staged installs
===============

As already explained above, our FC SIM 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.