# HG changeset patch # User Mychaela Falconia # Date 1616355507 0 # Node ID 0fec41a1013172d953b96a0d3420b8533b65ee0b # Parent 0299c16f2ab17ad9ede0d576764a9eb646677a5f INSTALL article written diff -r 0299c16f2ab1 -r 0fec41a10131 INSTALL --- /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.