--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/INSTALL	Sat Feb 18 23:24:54 2023 +0000
@@ -0,0 +1,96 @@
+Dependency graph
+================
+
+The complete Themyscira GSM codec libraries & utilities package as presented
+here consists of two principal parts:
+
+Division 1: libgsmefr and libgsmfrp, the two C code libraries intended to be
+usable by other software;
+
+Division 2: various command line utilities that were developed under the
+umbrella of this project and are being released accordingly.
+
+Division 2 components have a compile-time dependency on Division 1 (some of
+these Division 2 command line utilities link with libgsmefr or libgsmfrp), but
+not the other way around: neither libgsmefr nor libgsmfrp has any dependency on
+any other part of this package.
+
+However, the original GSM 06.10 library (libgsm) from 1990s is a required
+dependency for several components of the present Themyscira package: libgsmfrp
+and several Division 2 command line utilities have a compile-time dependency on
+<gsm.h> header file provided by libgsm, and several Division 2 utilities also
+have a link dependency on libgsm itself.  Therefore, libgsm should be considered
+a hard dependency for the present GSM codec libraries & utilities package as a
+whole, and it needs to be installed system-wide prior to compiling the present
+software.
+
+Compiling and installing Themyscira libraries and utilities
+===========================================================
+
+Running 'make' at the top level of the present gsm-codec-lib package will
+compile both Division 1 and Division 2 software components (both libraries and
+utilities), with the top level Makefile codifying the dependency graph among
+them.  Installation, however, is a little more complicated in that there is no
+single 'make install' target at the top level - instead of a single install
+target, the top Makefile provides two separate installation targets:
+
+make install-lib	Install libgsmefr and libgsmfrp system-wide:
+			gsm_efr.h and gsm_fr_preproc.h are installed in
+			/usr/local/include; libgsmefr.a and libgsmfrp.a are
+			installed in /usr/local/lib.  Superuser privileges
+			are usually required to write to these directories.
+
+make install-utils	Install Division 2 command line utilities into
+			/opt/freecalypso/bin directory, which is non-standard
+			in the muggle world but has been established in our
+			Themyscira community as the location for Themyscira-
+			developed command line utilities working with GSM.
+
+The just-described separation between install-lib and install-utils targets has
+been created because of the difference in install paths: libraries and their
+header files that need to be easily findable and usable by other people's
+unrelated software need to be installed under /usr/local, requiring su to root
+before each install cycle, whereas /opt/freecalypso/bin (writable without root
+privileges on the Mother's development machine) is much more convenient for
+Division 2 command line utilities.
+
+However, the present gsm-codec-lib package differs from FreeCalypso host tools
+and SIM tools packages in that in the present package, you ARE allowed to freely
+change these installation directories to fit your own preferences.  FC host
+tools and FC SIM tools packages carry very strong admonitions in their INSTALL
+documents to the effect that they MUST be installed under /opt/freecalypso and
+that this path cannot be changed; this strict imposition is made because of
+strong intercomponent dependencies within those software suites, with different
+components invoking each other or looking for their support files using hard-
+coded absolute pathnames.  But the present gsm-codec-lib package is different:
+you are free to move our Division 2 command line utilities from
+/opt/freecalypso/bin to /usr/local/bin or anywhere else you like, and you are
+likewise free to move our Division 1 libraries from /usr/local/{include,lib} to
+whatever location would be most appropriate in your environment.
+
+To change installation directories, you will need to edit subdirectory Makefiles
+as follows:
+
+Division 1:
+
+	libgsmefr/Makefile
+	libgsmfrp/Makefile
+
+Division 2:
+
+	amrconv/Makefile
+	efrtest/Makefile
+	frtest/Makefile
+	miscutil/Makefile
+	pcap/Makefile
+
+pcap subdirectory and libpcap dependency
+========================================
+
+The present package includes (as part of Division 2) a set of command line
+utilities for analyzing RTP streams that have been captured with tcpdump or
+equivalent tools in pcap format.  These utilities, described in the
+doc/RTP-analysis article, are built in the pcap subdirectory and naturally
+depend on libpcap.  If your system lacks libpcap and you don't need these RTP
+analysis utilities, you can edit the top level Makefile and remove pcap from
+the list in SUBDIR_UTILS.