diff PACKAGING @ 435:0a01e1c4ea54

documentation: added some notes about the importance of preserving our /opt/freecalypso private directory hierarchy
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 04 Nov 2018 21:55:19 +0000 (2018-11-04)
parents
children
line wrap: on
line diff
--- /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.