# HG changeset patch # User Mychaela Falconia # Date 1541368519 0 # Node ID 0a01e1c4ea5482b120ae9861b91ffbafb1b8d060 # Parent 3ec8ef8b2d37a562360788264f1449e4cde7cc9a documentation: added some notes about the importance of preserving our /opt/freecalypso private directory hierarchy diff -r 3ec8ef8b2d37 -r 0a01e1c4ea54 INSTALL --- 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: diff -r 3ec8ef8b2d37 -r 0a01e1c4ea54 PACKAGING --- /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. diff -r 3ec8ef8b2d37 -r 0a01e1c4ea54 doc/opt-freecalypso-tree --- /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.