FreeCalypso > hg > gsm-codec-lib

annotate INSTALL @ 208:13d27ff5b5df

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
add documents for release
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 18 Feb 2023 23:24:54 +0000
parents
children 34f8549ff0b1
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
208
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 Dependency graph
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 ================
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 The complete Themyscira GSM codec libraries & utilities package as presented
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 here consists of two principal parts:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 Division 1: libgsmefr and libgsmfrp, the two C code libraries intended to be
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 usable by other software;
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 Division 2: various command line utilities that were developed under the
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 umbrella of this project and are being released accordingly.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 Division 2 components have a compile-time dependency on Division 1 (some of
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 these Division 2 command line utilities link with libgsmefr or libgsmfrp), but
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 not the other way around: neither libgsmefr nor libgsmfrp has any dependency on
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 any other part of this package.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 However, the original GSM 06.10 library (libgsm) from 1990s is a required
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 dependency for several components of the present Themyscira package: libgsmfrp
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 and several Division 2 command line utilities have a compile-time dependency on
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 <gsm.h> header file provided by libgsm, and several Division 2 utilities also
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 have a link dependency on libgsm itself. Therefore, libgsm should be considered
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 a hard dependency for the present GSM codec libraries & utilities package as a
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 whole, and it needs to be installed system-wide prior to compiling the present
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 software.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 Compiling and installing Themyscira libraries and utilities
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 ===========================================================
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 Running 'make' at the top level of the present gsm-codec-lib package will
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 compile both Division 1 and Division 2 software components (both libraries and
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 utilities), with the top level Makefile codifying the dependency graph among
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 them. Installation, however, is a little more complicated in that there is no
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 single 'make install' target at the top level - instead of a single install
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 target, the top Makefile provides two separate installation targets:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 make install-lib Install libgsmefr and libgsmfrp system-wide:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 gsm_efr.h and gsm_fr_preproc.h are installed in
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 /usr/local/include; libgsmefr.a and libgsmfrp.a are
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 installed in /usr/local/lib. Superuser privileges
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 are usually required to write to these directories.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 make install-utils Install Division 2 command line utilities into
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 /opt/freecalypso/bin directory, which is non-standard
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 in the muggle world but has been established in our
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 Themyscira community as the location for Themyscira-
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 developed command line utilities working with GSM.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 The just-described separation between install-lib and install-utils targets has
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 been created because of the difference in install paths: libraries and their
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 header files that need to be easily findable and usable by other people's
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 unrelated software need to be installed under /usr/local, requiring su to root
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 before each install cycle, whereas /opt/freecalypso/bin (writable without root
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 privileges on the Mother's development machine) is much more convenient for
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 Division 2 command line utilities.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 However, the present gsm-codec-lib package differs from FreeCalypso host tools
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 and SIM tools packages in that in the present package, you ARE allowed to freely
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 change these installation directories to fit your own preferences. FC host
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 tools and FC SIM tools packages carry very strong admonitions in their INSTALL
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 documents to the effect that they MUST be installed under /opt/freecalypso and
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 that this path cannot be changed; this strict imposition is made because of
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 strong intercomponent dependencies within those software suites, with different
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 components invoking each other or looking for their support files using hard-
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 coded absolute pathnames. But the present gsm-codec-lib package is different:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 you are free to move our Division 2 command line utilities from
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 /opt/freecalypso/bin to /usr/local/bin or anywhere else you like, and you are
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 likewise free to move our Division 1 libraries from /usr/local/{include,lib} to
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 whatever location would be most appropriate in your environment.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 To change installation directories, you will need to edit subdirectory Makefiles
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 as follows:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 Division 1:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 libgsmefr/Makefile
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 libgsmfrp/Makefile
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 Division 2:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 amrconv/Makefile
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 efrtest/Makefile
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 frtest/Makefile
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 miscutil/Makefile
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 pcap/Makefile
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 pcap subdirectory and libpcap dependency
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 ========================================
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 The present package includes (as part of Division 2) a set of command line
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 utilities for analyzing RTP streams that have been captured with tcpdump or
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 equivalent tools in pcap format. These utilities, described in the
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 doc/RTP-analysis article, are built in the pcap subdirectory and naturally
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 depend on libpcap. If your system lacks libpcap and you don't need these RTP
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 analysis utilities, you can edit the top level Makefile and remove pcap from
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 the list in SUBDIR_UTILS.