--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/INSTALL	Sun Mar 21 19:38:27 2021 +0000
@@ -0,0 +1,110 @@
+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.