diff INSTALL @ 454:4b6fa53a8240

INSTALL: document the new way
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 10 May 2024 06:19:24 +0000
parents 34f8549ff0b1
children a53225b44ea5
line wrap: on
line diff
--- a/INSTALL	Fri May 10 05:45:46 2024 +0000
+++ b/INSTALL	Fri May 10 06:19:24 2024 +0000
@@ -4,81 +4,42 @@
 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 1: libgsmefr, libgsmfr2 and libtwamr, the set of 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.
+Division 2 components have a compile-time dependency on Division 1 (most of
+these Division 2 command line utilities link with the libraries), but not the
+other way around: none of the core libraries have any dependency on any other
+part of this package, not even on each other.
 
-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.
+Previous versions of gsm-codec-lib suite had a dependency on libgsm, the
+original GSM 06.10 implementation library from 1990s, and our suite was
+originally architectured as extending and building on top of libgsm.  However,
+this dependency has now been eliminated, and our new GSM codec libraries and
+utilities suite is now completely independent from historical libgsm.
 
 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.
+The configuration and build process has been fully revamped since previous
+versions:
 
-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.
+* You now need to run ./configure before running 'make' - however, please note
+  that our ./configure script is hand-coded, not Autotools/autohell, hence
+  there is no autoreconf nonsense involved.
 
-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.
+* When you run ./configure, you get the opportunity to either leave CC=, CFLAGS=
+  and the install prefix at their default values, or change them to your own
+  preferences.
 
-To change installation directories, you will need to edit subdirectory Makefiles
-as follows:
-
-Division 1:
+* There are no more install-lib and install-utils targets, just regular
+  'make install' that installs everything into whichever prefix you chose at
+  configure time.
 
-	libgsmefr/Makefile
-	libgsmfrp/Makefile
-
-Division 2:
-
-	amrconv/Makefile
-	efrtest/Makefile
-	frtest/Makefile
-	miscutil/Makefile
+The default install prefix is /opt/themwi; to change it, pass the standard
+--prefix=/wherever option to ./configure script.  The default compilation
+settings are CC=gcc and CFLAGS=-O2; to change them, pass CC=my-whatever-cc
+and/or CFLAGS="-fwhatever-flags" to configure.