--- /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.