FreeCalypso > hg > freecalypso-docs

comparison Install-location @ 103:c5f1f936dec5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Install-location: new article
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 20 Nov 2023 08:28:16 +0000
parents
children 12424010d7b8
comparison
equal deleted inserted replaced
102:49be28a15768 103:c5f1f936dec5
1 FreeCalypso software install location
2 =====================================
3
4 FreeCalypso queendom includes several software packages that are meant to be
5 installed on the user's general-purpose Unix/Linux host computer such as a
6 Linux PC or laptop. The principal component packages in this category are FC
7 host tools (for operating on GSM MS devices), FC SIM tools (for operating on
8 SIM cards) and FC USB-serial tools (for operating on FTDI and Silabs chips) -
9 but these listed tool packages are not the only ones. All FC software packages
10 that run on a general-purpose Unix/Linux host computer are meant to be installed
11 in one specific file system location; the present article applies to all of
12 these packages.
13
14 The install location for all FC host software packages is fixed as
15 /opt/freecalypso - this install location is NOT changeable. The directory tree
16 that exists under /opt/freecalypso is defined by the Mother of FreeCalypso in
17 her sole authority, and it includes both FHS-style and non-FHS-style,
18 FC-specific subdirectories. The following subdirectories are currently defined
19 under /opt/freecalypso:
20
21 (FHS-style)
22
23 bin All Unix/Linux host binaries are installed here.
24
25 include Some FC host software components provide header files that are
26 intended to be used by other (later in the dependency graph) FC
27 host sw components. FC host tools rvinterf headers are
28 installed here currently, used by fc-rfcal-tools.
29
30 lib Currently hypothetical, may be used in the future similarly to
31 include subdir.
32
33 (non-FHS-style, FC-specific)
34
35 aud-* Images of /aud FFS directory subtree (audio mode config files)
36 for different supported FreeCalypso devices, either FC hardware
37 products or aftermarket configurations.
38
39 batteries Collection of battery discharge threshold configuration files.
40
41 buz FFS subtree with PWT buzzer melodies, to be uploaded into /buz
42 on those FC devices that feature a traditional ringing buzzer.
43
44 charging Collection of battery charging configuration files.
45
46 cp2102 CP2102 baud rate tables and EEPROM patch files.
47
48 fluid Helper files for fluid-mnf port.
49
50 ftdi FTDI EEPROM configuration files.
51
52 gcc The recommend install location for our ARM7 gcc toolchain is
53 /opt/freecalypso/gcc.
54
55 helpfiles Help files for those FC host utilities which implement a help
56 command.
57
58 loadtools Hardware parameter files and init scripts which underlie the
59 all-important -h option to fc-loadtool, fc-iram and fc-xram,
60 collectively known as loadtools.
61
62 mel FFS subtree with E1 melodies, to be uploaded into /mel on those
63 FC devices that will use a voice path loudspeaker for ringing.
64
65 rfcal This subdir only appears if you are doing RF calibration and
66 install fc-rfcal-tools, and some of the necessary config files
67 under that subdir you have to create yourself using your own RF
68 knowledge specific to your particular setup.
69
70 scripts Command scripts for FC host tools other than fc-loadtool,
71 currently for fc-fsio.
72
73 sim-data SIM card database files for FC SIM tools.
74
75 sim-scripts Command scripts and associated "canned" data files for
76 fc-simtool and fc-uicc-tool.
77
78 target-bin ARM7 target binaries for Calypso GSM MS devices.
79
80 User interaction with /opt/freecalypso file system tree
81 =======================================================
82
83 The only subdirectory under /opt/freecalypso which all users need to be aware
84 of is /opt/freecalypso/bin - all executable binaries are installed there, hence
85 you need to either add this directory to your PATH or make symlinks from some
86 "standard" binary directory to ours. Most other subdirectories and files that
87 reside in them are accessed "under the hood" by tools that need them - however,
88 there are times when various "canned" workflow instructions will direct you to
89 type out the path to some file or another that reside in some FC-specific
90 location somewhere in /opt/freecalypso tree. The beauty of this fixed
91 /opt/freecalypso installation directory is that as long as you follow the rules
92 and don't try to outsmart the Mother, these "canned" instructions will always
93 work on every installation, not affected by any local variations.
94
95 Interdependencies between different FC tools
96 ============================================
97
98 Many FreeCalypso host tool programs depend on other FC tool binaries, invoking
99 them behind the scenes as needed. In cases where the tool depending on other
100 FC tool binaries is itself a compiled C program, the full path under
101 /opt/freecalypso/bin is always used. The same approach is also used in the
102 case of simplest shell script wrappers - however, most higher-level FC tools
103 that are implemented as shell scripts expect their subordinate tools (binaries
104 or subordinate shell scripts) to be accessible via current PATH.
105
106 Optional symlinks to FC tool binaries
107 =====================================
108
109 Given that FreeCalypso host tool programs need to be accessible via shell
110 search path, without manually typing out the full path on each invokation,
111 there are two possible solutions:
112
113 Option 1: add /opt/freecalypso/bin to your PATH. This option is ideal for
114 those who use FC host tools heavily and regularly, on machines where such heavy
115 and regular usage takes place.
116
117 Option 2: make symbolic links from some "standard" binary install location
118 (e.g., /usr/bin or /usr/local/bin) to /opt/freecalypso/bin for each installed
119 FC host tool program (binary or installed shell script). This option should be
120 preferred for installations where only some FreeCalypso utilities are expected
121 to be used, and only rarely/occasionally - or where the desire is to make the
122 utilities appear "ordinary", without making the user enter FC queendom
123 explicitly by adding /opt/freecalypso/bin to their PATH.
124
125 To make it easier to automate Option 2, new versions of FC host sw component
126 packages include a file in the source distribution named Installed-binaries.
127 This file lists, one per line, the names of all binaries (or shell scripts)
128 installed by the package in question in /opt/freecalypso/bin - the intent is
129 that this file will be used as the list of symlinks to be created.
130
131 Please also note that if you going for this Option 2, you really do need to
132 create symbolic links, NOT move the actual installed binaries! Moving FC tool
133 binaries out of /opt/freecalypso/bin will break every instance where one FC
134 program invokes another by absolute pathname - so don't do it. Locating and
135 patching all instances of another program invokation is NOT an acceptable
136 solution - there may be invokations from other FC software components which you
137 are not considering. In short. don't try to outsmart the Mother!
138
139 Why, why, why?
140 ==============
141
142 The Mother of FreeCalypso is fully aware that this requirement of fixed paths
143 under /opt/freecalypso runs totally counter to typical Unix/Linux application
144 software development and packaging conventions. The latter conventions call
145 for changeable paths: the person compiling or packaging the application chooses
146 the install location via ./configure --prefix option or some equivalent means,
147 and the software obeys. If FreeCalypso followed this convention, all of our
148 FC-specific, non-FHS-relevant stuff would be in either /usr/share/freecalypso or
149 /usr/local/share/freecalypso depending on how the software was installed by
150 each given user: via packaging, or by direct compilation and installation from
151 source.
152
153 In the earliest years of FreeCalypso, all binaries were installed into
154 /usr/local/bin and all support files were in /usr/local/share/freecalypso.
155 The big and ever-controversial decision to move to /opt/freecalypso was made
156 in late 2016, and all of justifying reasons back then still hold true today:
157
158 * There are all kinds of occasions where one needs to type the full path to
159 some file in one of FC-specific, non-FHS-relevant directories, and typing
160 /opt/freecalypso is much shorter than /usr/share/freecalypso, let alone
161 /usr/local/share/freecalypso.
162
163 * The number of different support files (FC-specific, non-FHS-relevant) keeps
164 growing, and so does their complex organization. Having all of these files
165 reside at fixed pathnames (as opposed to pathnames that change based on the
166 whim of whoever does sw installation or packaging) makes life much easier.
167
168 * Implementing a ./configure system that dynamically changes pathnames for our
169 myriad of FC-specific, non-FHS-relevant support and data files would be a
170 huge pain, and more work than is justifiable.
171
172 * FreeCalypso is not a single software package, but a complex queendom. We
173 have separate sw packages for FC host tools (operating on GSM MS devices),
174 SIM card tools, RF calibration tools, USB-serial tools etc - trying to put
175 all of them into one package would be difficult, inconvenient and unnatural,
176 hence they are separate sw packages. But these separate sw packages have
177 interdependencies, sometimes mandatory (fc-rfcal-tools strictly depend on FC
178 host tools), othertimes optional (intertie between FC host tools and FC SIM
179 tools is strictly optional, appearing only in certain workflows), and they do
180 belong to the same FreeCalypso queendom. With a fixed mandated install path,
181 each sw component in the queendom can freely reference bits from other
182 components - whereas if we adopted the conventional packaging paradigm, we
183 would have to deal with the possibility of different packages being installed
184 under different paths.
185
186 Don't try to outsmart the Mother!
187 =================================
188
189 We are aware of certain rogue packagers who were determined to have their way
190 and change the install location to something other than /opt/freecalypso, no
191 matter how much we admonish against doing so. In the world of freely published
192 software distributed as source, it is of course impossible to actually enforce
193 any kind of usage rules - however, we do operate with the following set of
194 policies:
195
196 * Any packagings of FreeCalypso software in which the install location has been
197 changed to something other than /opt/freecalypso are considered to be rogue
198 packages. Such packages shall be regarded as malware - do not install,
199 do not use!
200
201 * We shall not, under any circumstances, provide any kind of technical support
202 to anyone who uses a rogue package. Anyone using a rogue package will be
203 told to migrate to either direct from-source installation or a properly
204 constructed downstream package, with /opt/freecalypso install location
205 preserved, being any other issues can be addressed.