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, before any other issues can be addressed.