The present document is intended to be a guide for any parties who are going to
turn the present upstream gsm-codec-lib source package into user-friendly binary
packages for specific distributions.

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:

* 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; at Themyscira HQ we use various custom directories under /opt for
  both Osmocom CNI and our own ThemWi components, but no one else is being
  asked to do what we do!  We now follow the general free sw community standard
  whereby the default install location is /usr/local, but you are always free
  to change it to wherever you like with the standard --prefix option to
  configure.

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.

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:

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.

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
================

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.

Downstream package version numbers for command line utilities packages are up
to the discretion of packaging maintainers; using gsm-codec-lib tarball release
numbers is acceptable.

Patience, please
================

Please make downstream package releases *only* from officially published tarball
releases of gsm-codec-lib - please do *not* make packaged builds or "releases"
from our Mercurial repository.  Any time we have a new development that is
expected to be useful to downstream end users, we shall make a proper tarball
release, and if there are any changes in the libraries, we shall assign new
semantic versions as appropriate.