# HG changeset patch # User Mychaela Falconia # Date 1676762694 0 # Node ID 13d27ff5b5df6700cd5d122988cdf50913df8b2b # Parent 10f11a2d40423eaff31bd0ac6140f4b23b0941c2 add documents for release diff -r 10f11a2d4042 -r 13d27ff5b5df INSTALL --- /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 + 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. diff -r 10f11a2d4042 -r 13d27ff5b5df LICENSE --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/LICENSE Sat Feb 18 23:24:54 2023 +0000 @@ -0,0 +1,11 @@ +The present GSM codec libraries & utilities package has been produced by the +Presiding Sisterhood (government) of the Women's Republic of Themyscira as part +of our Themyscira Wireless technical initiative. Because this development is a +public works project, the resulting software is free to the world, i.e., public +domain: all people anywhere in the world, of all genders, can use, copy, and +modify it freely as they wish, including unlimited redistribution with or +without modifications. We do ask, however, that any non-Themyscira +modifications to this software be clearly noted and attributed. + +The libgsmefr component of the present software package is based on the EFR +reference code from the European Telecommunications Standards Institute (ETSI). diff -r 10f11a2d4042 -r 13d27ff5b5df Library-versions --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Library-versions Sat Feb 18 23:24:54 2023 +0000 @@ -0,0 +1,6 @@ +The two Themyscira GSM codec libraries (libgsmefr and libgsmfrp) use Semantic +Versioning, as described at . In the present source +release package, the semantic versions of the two libraries are as follows: + +libgsmefr version 1.0.0 +libgsmfrp version 1.0.0 diff -r 10f11a2d4042 -r 13d27ff5b5df PACKAGING --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/PACKAGING Sat Feb 18 23:24:54 2023 +0000 @@ -0,0 +1,60 @@ +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. + +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: + +libgsmefr package: just libgsmefr.a and its associated gsm_efr.h header file. + +libgsmfrp package: just libgsmfrp.a and its associated gsm_fr_preproc.h header +file. Given that depends on from classic libgsm, +the latter library (libgsm) should probably be officially declared as a +dependency for libgsmfrp. + +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. + +themwi-pcap-utils: the set of command line utilities built in the pcap +subdirectory, with a dependency on libpcap but no dependencies on any GSM +libraries. + +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. + +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 +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.