--- a/INSTALL	Sun Nov 04 19:24:46 2018 +0000
+++ b/INSTALL	Sun Nov 04 21:55:19 2018 +0000
@@ -6,6 +6,7 @@
 old-fashioned and refuses to use autotools (sorry, we aren't GNU), hence
 various hard-coded paths under /opt/freecalypso are sprinkled in bazillion
 places - thus changing this fixed install location is deemed to be impractical.
+See PACKAGING and doc/opt-freecalypso-tree for more notes on this subject.
 
 In order to compile and install our host tools, follow these steps:
 

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/PACKAGING	Sun Nov 04 21:55:19 2018 +0000
@@ -0,0 +1,56 @@
+It has been brought to the Mother's attention that some people don't like the
+way our FC host tools are designed to be installed under /opt/freecalypso as
+opposed to some standard location like /usr/local, and that some people have
+been patching our Makefiles and code to move our installed binaries (and perhaps
+some of the support files as well) to other locations which they like better.
+
+PLEASE DON'T DO IT, especially if you are making a package or a build or setup
+or install script to be used by more than just you.  FC host tools are a very
+complex package with a lot of interrelations between different tools, many
+tools in our suite internally invoke other tools by their /opt/freecalypso/bin
+absolute pathnames, some tools are designed to be invoked both by human users
+and by other tools (rvinterf is a prime example), and there are many support
+files used by various tools.  If you try to outsmart the Mother and change the
+install location to something other than what I designed it to be, you will
+inevitably break something, and you probably won't notice the breakage because
+a typical casual user only uses a very small subset of our tools.  Furthermore,
+if you move the install location, you will certainly break our various
+additional tools which are not included in the core FC host tools package but
+are meant to be installed on top of it, as all of them expect and require the
+/opt/freecalypso directory hierarchy described in doc/opt-freecalypso-tree.
+
+If your goal is to have our installed binaries accessible with a standard PATH
+without adding /opt/freecalypso/bin to it, the correct solution is to list the
+binaries installed in /opt/freecalypso/bin and make a symlink to each of these
+binaries from /usr/bin or from /usr/local/bin or from wherever you like.  Use
+symlinks, don't move the binaries themselves!  If you move the actual binaries,
+you will break those tools which internally invoke other tools, which we do a
+lot.
+
+If you still dislike the whole idea, consider the way Firefox does it: official
+release binaries from Mozilla are meant to be installed under /usr/lib/firefox
+or /usr/lib/firefox-$VERSION, the stuff inside that directory looks nothing like
+FHS, it is private to Firefox just like our /opt/freecalypso directory hierarchy
+is private to FreeCalypso, and the user makes one symlink from /usr/bin/firefox
+to /usr/lib/firefox-$VERSION/firefox or wherever the full complex package
+resides.  If you can live with Firefox and other major application packages
+having their own non-FHS private directory trees, you can surely live with
+FreeCalypso doing the same.
+
+Why did we make our prefix /opt/freecalypso and not /usr/lib/freecalypso or
+/usr/local/freecalypso?  Because there are many, many places where the full
+absolute pathname needs to be typed, and the location we chose is the shortest
+among other sensible options.
+
+Anyone who is going to make binary packages of our FC host tools (presumably
+for use on systems on which compilation from source is difficult) and wishes to
+have their packaging officially endorsed by the upstream MUST follow these
+guidelines:
+
+* The complete set of tools and support files MUST be included as if one built
+  and installed our package from the official source, without omitting or
+  breaking any part which you might consider unimportant.
+
+* Everything MUST be installed under /opt/freecalypso exactly as designed by
+  the Mother; symlinks to binaries under /opt/freecalypso/bin from a more user-
+  friendly location may optionally be included.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/opt-freecalypso-tree	Sun Nov 04 21:55:19 2018 +0000
@@ -0,0 +1,48 @@
+The /opt/freecalypso host directory tree used by the present FC host tools
+package and by various add-ons to it does NOT follow the traditional Unix/Linux
+file system hierarchy standard (FHS), instead it is a highly specialized
+directory tree that is meant to be private to FreeCalypso, with its structure
+defined solely by the Mother and no one else.  The following subdirectories are
+currently defined:
+
+aud-*: these directories appear if you install our optional
+fc-audio-config package, and contain subtrees to be uploaded by
+production line scripts into target device FFS under /aud via fc-fsio.
+
+batteries and charging: these subtrees come from fc-battery-conf
+(optional just like fc-audio-config) and are meant to be used with
+fc-fsio write-battery-table and write-charging-config commands.
+
+bin and include are the only subdirectories under /opt/freecalypso
+which follow traditional UNIX directory layout; include was added so
+that packages external to the core FC host tools package like
+fc-rfcal-tools and freecalypso-ui-dev can use rvinterf headers.
+
+gcc: the recommend install location for our ARM7 gcc toolchain is
+/opt/freecalypso/gcc.
+
+helpfiles subdir contains help files for those FC host utilities which
+implement a help command.
+
+loadtools subdir contains 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.
+
+rfcal 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.
+
+target-bin contains ARM7 target binaries used under the hood by
+loadtools.
+
+The basic minimal form of the /opt/freecalypso tree is populated when
+you install FC host tools, but it is further enriched if and when you
+install further add-ons (fc-audio-config, fc-battery-conf,
+fc-rfcal-tools) which are more specialized and not required for all
+users.  I expect to have more additions in the future: for example,
+when we start using the Melody E1 mechanism in our planned FC Libre
+Dumbphone, there will be a FreeCalypso ringtones package that will
+install E1-format melody files somewhere under /opt/freecalyso, to be
+subsequently uploaded into the actual phones via fc-fsio, initially at
+production time and optionally by end users.