FreeCalypso > hg > fc-sim-tools

annotate INSTALL @ 55:a754d4f117cf

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Formatting-thoughts: new article, split from Sysmocom-SIM-notes and updated for Grcard situation
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 22 Mar 2021 21:28:32 +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.