FreeCalypso > hg > fc-sim-tools

comparison INSTALL @ 52:0fec41a10131

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
INSTALL article written
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 21 Mar 2021 19:38:27 +0000
parents
children
comparison
equal deleted inserted replaced
51:0299c16f2ab1 52:0fec41a10131
1 Installation location
2 =====================
3
4 The present FC SIM tools package is part of the greater FreeCalypso software
5 family, therefore, these tools are designed to be installed in the
6 /opt/freecalypso directory hierarchy on your system. Changing this install
7 location is NOT ALLOWED: if you try to change it, you will break things, and I,
8 the author of this software, will not provide any help or support whatsoever to
9 anyone who seeks to change our fixed installation location.
10
11 Building and installing FC SIM tools
12 ====================================
13
14 In order to compile and install our tools, follow these steps:
15
16 1: Run 'make' as a regular user (not root) to compile the software.
17
18 2: Decide if you prefer to have the /opt/freecalypso directory and everything
19 under it to be owned by root or by your non-root uid.
20
21 If you prefer /opt/freecalypso to be root-owned:
22
23 3A: Run 'make install' as root; the install rule in the
24 Makefile will do mkdir -p /opt/freecalypso as its first step.
25
26 4A: You are done!
27
28 If you prefer /opt/freecalypso to be owned by your "regular" non-root uid:
29
30 3B: Become root just to create the /opt/freecalypso directory and chown it
31 to your non-root uid.
32
33 4B: Run 'make install' as your regular uid; it should succeed because you
34 should have made yourself the owner of /opt/freecalypso with full write
35 permission in the previous step.
36
37 5B: You are done!
38
39 fc-simtool and other binaries will be installed in /opt/freecalypso/bin; you
40 can either add this directory to your PATH or make symlinks from /usr/bin or
41 /usr/local/bin or wherever.
42
43 Including or excluding pcsc back end
44 ====================================
45
46 The main body of software in the present package (fc-simtool, fc-uicc-tool and
47 all accessory programs except pcsc-specific ones) has zero compile-time
48 dependencies, needing only a working C compiler, standard system header files
49 under /usr/include, and libc. However, one of the 3 card access back ends
50 supported by our tools is pcsc, and that back end requires libpcsclite and its
51 header files in order to compile.
52
53 You can include or exclude this pcsc back end depending on your needs. If you
54 wish to use a professional card reading/programming station like HID Omnikey
55 3121 or its pocket sibling Omnikey 6121 (both of which are USB CCIDs), then you
56 will need to go through the pain of getting pcsc-lite up and running on your
57 system, including a working installation of libpcsclite and its header files -
58 going through this pcsc-lite software stack is the only way to operate these
59 USB CCIDs. OTOH, if you are going to be a more casual (not professional) user
60 of FC SIM tools, only needing to occasionally poke at a SIM card inside your
61 Calypso phone or perhaps in a serial SIM reader, without ever using professional
62 card readers of the type that require pcsc-lite, then you can simply exclude the
63 part of our software suite that needs pcsc-lite (the pcsc back end), and enjoy
64 traditional FreeCalypso software with zero compile-time dependencies.
65
66 To exclude pcsc from your build, change the standard 'make' and 'make install'
67 commands as follows:
68
69 make PCSC=
70 make PCSC= install
71
72 CC= and CFLAGS= selection
73 =========================
74
75 Our Makefile hierarchy is set up to build with CC=gcc and CFLAGS=-O2 by default.
76 If you need to change either or both of these selections, you can do it by
77 adding CC= and/or CFLAGS= on the make invokation line, for example:
78
79 make CC=mygcc CFLAGS="-g -O2 -whatever-options"
80
81 Porting to systems other than Linux
82 ===================================
83
84 Most of the present software is written to be generic to any Unix, but the
85 Mother currently uses only Linux, thus no other systems have been tested. One
86 component that is known to be Linux-specific is the serial SIM reader back end,
87 which is written to work with arbitrary UART baud rates and not just RS-232
88 standard ones like 9600 bps - see doc/Serial-SIM-readers for the details.
89
90 Staged installs
91 ===============
92
93 As already explained above, our FC SIM tools need to be installed under
94 /opt/freecalypso on your system in order to function correctly, and this runtime
95 location is not changeable. However, some users have requested an ability to
96 do a staged install: have the 'make install' operation install the finished
97 tree of files in some staging location, with the expectation that it will be
98 subsequently moved to /opt/freecalypso by some other mechanism. One use case
99 that has been presented to us was automated building of binary distribution
100 packages on a build host where writing to /opt/freecalypso is not allowed.
101
102 If you need to make a staged install of this sort, you can do it like this:
103
104 make install INSTALL_PREFIX=/home/me/my-fc-staging-area
105
106 Please note that this INSTALL_PREFIX= scheme changes *only* the location where
107 'make install' will deposit the installable files; it does NOT change the
108 location where our programs will look for other programs and helper files: the
109 latter location is hard-coded as /opt/freecalypso is bazillion places throughout
110 our code base.