# HG changeset patch # User Mychaela Falconia # Date 1700468896 0 # Node ID c5f1f936dec592c122e38dd46849add53770cb40 # Parent 49be28a15768d1454ad2ba6e9db14e3deaaa94ec Install-location: new article diff -r 49be28a15768 -r c5f1f936dec5 Install-location --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Install-location Mon Nov 20 08:28:16 2023 +0000 @@ -0,0 +1,205 @@ +FreeCalypso software install location +===================================== + +FreeCalypso queendom includes several software packages that are meant to be +installed on the user's general-purpose Unix/Linux host computer such as a +Linux PC or laptop. The principal component packages in this category are FC +host tools (for operating on GSM MS devices), FC SIM tools (for operating on +SIM cards) and FC USB-serial tools (for operating on FTDI and Silabs chips) - +but these listed tool packages are not the only ones. All FC software packages +that run on a general-purpose Unix/Linux host computer are meant to be installed +in one specific file system location; the present article applies to all of +these packages. + +The install location for all FC host software packages is fixed as +/opt/freecalypso - this install location is NOT changeable. The directory tree +that exists under /opt/freecalypso is defined by the Mother of FreeCalypso in +her sole authority, and it includes both FHS-style and non-FHS-style, +FC-specific subdirectories. The following subdirectories are currently defined +under /opt/freecalypso: + +(FHS-style) + +bin All Unix/Linux host binaries are installed here. + +include Some FC host software components provide header files that are + intended to be used by other (later in the dependency graph) FC + host sw components. FC host tools rvinterf headers are + installed here currently, used by fc-rfcal-tools. + +lib Currently hypothetical, may be used in the future similarly to + include subdir. + +(non-FHS-style, FC-specific) + +aud-* Images of /aud FFS directory subtree (audio mode config files) + for different supported FreeCalypso devices, either FC hardware + products or aftermarket configurations. + +batteries Collection of battery discharge threshold configuration files. + +buz FFS subtree with PWT buzzer melodies, to be uploaded into /buz + on those FC devices that feature a traditional ringing buzzer. + +charging Collection of battery charging configuration files. + +cp2102 CP2102 baud rate tables and EEPROM patch files. + +fluid Helper files for fluid-mnf port. + +ftdi FTDI EEPROM configuration files. + +gcc The recommend install location for our ARM7 gcc toolchain is + /opt/freecalypso/gcc. + +helpfiles Help files for those FC host utilities which implement a help + command. + +loadtools Hardware parameter files and init scripts which underlie the + all-important -h option to fc-loadtool, fc-iram and fc-xram, + collectively known as loadtools. + +mel FFS subtree with E1 melodies, to be uploaded into /mel on those + FC devices that will use a voice path loudspeaker for ringing. + +rfcal This subdir only appears if you are doing RF calibration and + install fc-rfcal-tools, and some of the necessary config files + under that subdir you have to create yourself using your own RF + knowledge specific to your particular setup. + +scripts Command scripts for FC host tools other than fc-loadtool, + currently for fc-fsio. + +sim-data SIM card database files for FC SIM tools. + +sim-scripts Command scripts and associated "canned" data files for + fc-simtool and fc-uicc-tool. + +target-bin ARM7 target binaries for Calypso GSM MS devices. + +User interaction with /opt/freecalypso file system tree +======================================================= + +The only subdirectory under /opt/freecalypso which all users need to be aware +of is /opt/freecalypso/bin - all executable binaries are installed there, hence +you need to either add this directory to your PATH or make symlinks from some +"standard" binary directory to ours. Most other subdirectories and files that +reside in them are accessed "under the hood" by tools that need them - however, +there are times when various "canned" workflow instructions will direct you to +type out the path to some file or another that reside in some FC-specific +location somewhere in /opt/freecalypso tree. The beauty of this fixed +/opt/freecalypso installation directory is that as long as you follow the rules +and don't try to outsmart the Mother, these "canned" instructions will always +work on every installation, not affected by any local variations. + +Interdependencies between different FC tools +============================================ + +Many FreeCalypso host tool programs depend on other FC tool binaries, invoking +them behind the scenes as needed. In cases where the tool depending on other +FC tool binaries is itself a compiled C program, the full path under +/opt/freecalypso/bin is always used. The same approach is also used in the +case of simplest shell script wrappers - however, most higher-level FC tools +that are implemented as shell scripts expect their subordinate tools (binaries +or subordinate shell scripts) to be accessible via current PATH. + +Optional symlinks to FC tool binaries +===================================== + +Given that FreeCalypso host tool programs need to be accessible via shell +search path, without manually typing out the full path on each invokation, +there are two possible solutions: + +Option 1: add /opt/freecalypso/bin to your PATH. This option is ideal for +those who use FC host tools heavily and regularly, on machines where such heavy +and regular usage takes place. + +Option 2: make symbolic links from some "standard" binary install location +(e.g., /usr/bin or /usr/local/bin) to /opt/freecalypso/bin for each installed +FC host tool program (binary or installed shell script). This option should be +preferred for installations where only some FreeCalypso utilities are expected +to be used, and only rarely/occasionally - or where the desire is to make the +utilities appear "ordinary", without making the user enter FC queendom +explicitly by adding /opt/freecalypso/bin to their PATH. + +To make it easier to automate Option 2, new versions of FC host sw component +packages include a file in the source distribution named Installed-binaries. +This file lists, one per line, the names of all binaries (or shell scripts) +installed by the package in question in /opt/freecalypso/bin - the intent is +that this file will be used as the list of symlinks to be created. + +Please also note that if you going for this Option 2, you really do need to +create symbolic links, NOT move the actual installed binaries! Moving FC tool +binaries out of /opt/freecalypso/bin will break every instance where one FC +program invokes another by absolute pathname - so don't do it. Locating and +patching all instances of another program invokation is NOT an acceptable +solution - there may be invokations from other FC software components which you +are not considering. In short. don't try to outsmart the Mother! + +Why, why, why? +============== + +The Mother of FreeCalypso is fully aware that this requirement of fixed paths +under /opt/freecalypso runs totally counter to typical Unix/Linux application +software development and packaging conventions. The latter conventions call +for changeable paths: the person compiling or packaging the application chooses +the install location via ./configure --prefix option or some equivalent means, +and the software obeys. If FreeCalypso followed this convention, all of our +FC-specific, non-FHS-relevant stuff would be in either /usr/share/freecalypso or +/usr/local/share/freecalypso depending on how the software was installed by +each given user: via packaging, or by direct compilation and installation from +source. + +In the earliest years of FreeCalypso, all binaries were installed into +/usr/local/bin and all support files were in /usr/local/share/freecalypso. +The big and ever-controversial decision to move to /opt/freecalypso was made +in late 2016, and all of justifying reasons back then still hold true today: + +* There are all kinds of occasions where one needs to type the full path to + some file in one of FC-specific, non-FHS-relevant directories, and typing + /opt/freecalypso is much shorter than /usr/share/freecalypso, let alone + /usr/local/share/freecalypso. + +* The number of different support files (FC-specific, non-FHS-relevant) keeps + growing, and so does their complex organization. Having all of these files + reside at fixed pathnames (as opposed to pathnames that change based on the + whim of whoever does sw installation or packaging) makes life much easier. + +* Implementing a ./configure system that dynamically changes pathnames for our + myriad of FC-specific, non-FHS-relevant support and data files would be a + huge pain, and more work than is justifiable. + +* FreeCalypso is not a single software package, but a complex queendom. We + have separate sw packages for FC host tools (operating on GSM MS devices), + SIM card tools, RF calibration tools, USB-serial tools etc - trying to put + all of them into one package would be difficult, inconvenient and unnatural, + hence they are separate sw packages. But these separate sw packages have + interdependencies, sometimes mandatory (fc-rfcal-tools strictly depend on FC + host tools), othertimes optional (intertie between FC host tools and FC SIM + tools is strictly optional, appearing only in certain workflows), and they do + belong to the same FreeCalypso queendom. With a fixed mandated install path, + each sw component in the queendom can freely reference bits from other + components - whereas if we adopted the conventional packaging paradigm, we + would have to deal with the possibility of different packages being installed + under different paths. + +Don't try to outsmart the Mother! +================================= + +We are aware of certain rogue packagers who were determined to have their way +and change the install location to something other than /opt/freecalypso, no +matter how much we admonish against doing so. In the world of freely published +software distributed as source, it is of course impossible to actually enforce +any kind of usage rules - however, we do operate with the following set of +policies: + +* Any packagings of FreeCalypso software in which the install location has been + changed to something other than /opt/freecalypso are considered to be rogue + packages. Such packages shall be regarded as malware - do not install, + do not use! + +* We shall not, under any circumstances, provide any kind of technical support + to anyone who uses a rogue package. Anyone using a rogue package will be + told to migrate to either direct from-source installation or a properly + constructed downstream package, with /opt/freecalypso install location + preserved, being any other issues can be addressed.