--- a/PACKAGING	Fri May 10 06:22:42 2024 +0000
+++ b/PACKAGING	Fri May 10 07:35:36 2024 +0000
@@ -2,42 +2,70 @@
 turn the present upstream gsm-codec-lib source package into user-friendly binary
 packages for specific distributions.
 
-The Mother's primary recommendation with regard to downstream packaging of the
-present software is that end-user binary packages should be divided more finely
-than the present source package.  At the present source level the two principal
-libraries (libgsmefr and libgsmfrp) are combined together with a bunch of
-command line utilities for reasons of compile-time dependency (utilities depend
-on libraries), and also for the purposes of library development and testing -
-but the same combination does not make much sense from a user's perspective.
-Therefore, it is our recommendation that the present source package be split as
-follows at the level of end-user distro packages:
+Naming and attribution
+======================
+
+Please note that the present GSM codec libraries and utilities suite should be
+properly classified as Themyscira software and not FreeCalypso.  Even though
+FreeCalypso and Themyscira software realms currently have the same maintainer,
+the two realms have different conventions that matter for packaging and
+configuration management:
 
-libgsmefr package: just libgsmefr.a and its associated gsm_efr.h header file.
+* FreeCalypso software components are intended for users and tinkerers who work
+  with GSM phone handsets, GSM MS development boards, SIM cards and related
+  mobile-side hardware.  That software realm uses a fixed /opt/freecalypso
+  directory hierarchy, non-FHS, which cannot be changed.
+
+* Themyscira software components are intended to run on server machines where
+  they will often need to interwork closely with Osmocom and other network
+  software.  Unlike FC, ThemWi software does _not_ require a fixed install
+  location; the Mother's home environment uses /opt/themwi by default (although
+  even here we sometimes have to work with multiple installs like /opt/themwi2
+  etc), but the intent is that users of ThemWi software should have just as much
+  freedom to choose their install location as users of Osmocom CNI.
+
+Toward this end, all ThemWi software beginning with the present package will
+have a ./configure script (hand-coded, no Autotools) that accepts the standard
+--prefix option, allowing the install prefix to be chosen freely.
 
-libgsmfrp package: just libgsmfrp.a and its associated gsm_fr_preproc.h header
-file.  Given that <gsm_fr_preproc.h> depends on <gsm.h> from classic libgsm,
-the latter library (libgsm) should probably be officially declared as a
-dependency for libgsmfrp.
+Note that DESTDIR= setting on 'make install' is now supported!  What is the
+difference between --prefix argument to ./configure and DESTDIR= on the 'make
+install' command?  Answer: --prefix indicates the final location where the
+software is meant to reside in its installed state, DESTDIR= is a local
+modification for the 'make install' operation only, intended for staged installs
+as happen in package build scripts.
+
+Package splitting
+=================
+
+There are several different ways how the full GSM codec libraries and utilities
+suite may be kept together or divided in binary packages:
 
-gsm-codec-utils (or themwi-gsm-codec-utils or themwi-codec-utils) package: all
-command line utilities built and installed in amrconv, efrtest, frtest and
-miscutil subdirectories.  This package will depend on libgsmefr, libgsmfrp and
-classic libgsm - the latter is pre-existing software, not provided by
-Themyscira.
+1) The simplest way is to have one binary package built from the source package,
+   containing all libraries and utilities.
+
+2) The next option is to produce one package with libraries and a second package
+   with utilities.  The utilities package will then depend on the libraries
+   package, but not the other way around.
 
-With the division recommended above, the set of end-user packages will exhibit
-a sensible functional division from the user's perspective, and a clean and
-sensible dependency graph.
+3) The finest division would be to produce a separate package for each codec
+   library (libgsmefr, libgsmfr2, libtwamr) and then a utilities package.  The
+   set of utilities included in the present suite does not have clear-cut
+   logical divisions, hence it would probably make the most sense to have just
+   one utilities packages that depends on all of the libraries.
+
+The choice of approach is left to the discretion of individual packagers or
+package maintainers.
 
 Package versions
 ================
 
-The two library packages (libgsmefr and libgsmfrp) should be versioned with
-their own proper semantic versions listed in the Library-versions document, as
-opposed to the larger gsm-codec-lib tarball release version.  If a later
-gsm-codec-lib tarball release exhibits no changes in the libraries (the only
-changes are in the command line utilities) or if only one of the two libraries
-exhibits changes (as indicated with a new semantic version), then NO new
+If separate packages are made for each codec library, these packages should be
+versioned with their own proper semantic versions listed in the Library-versions
+document, as opposed to the larger gsm-codec-lib tarball release version.  If a
+later gsm-codec-lib tarball release exhibits no changes in the libraries (the
+only changes are in the command line utilities) or if only some of the libraries
+exhibit changes (as indicated with a new semantic version), then NO new
 downstream packages should be made for unchanged libraries - instead already
 made binary packages for that library version (SemVer) should be retained.