FreeCalypso > hg > fc-sim-tools

annotate INSTALL @ 93:6041c601304d

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