FreeCalypso > hg > gsm-codec-lib

annotate PACKAGING @ 585:3c6bf0d26ee7 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
TW-TS-005 reader: fix maximum line length bug TW-TS-005 section 4.1 states: The maximum allowed length of each line is 80 characters, not including the OS-specific newline encoding. The implementation of this line length limit in the TW-TS-005 hex file reader function in the present suite was wrong, such that lines of the full maximum length could not be read. Fix it. Note that this bug affects comment lines too, not just actual RTP payloads. Neither Annex A nor Annex B features an RTP payload format that goes to the maximum of 40 bytes, but if a comment line goes to the maximum allowed length of 80 characters not including the terminating newline, the bug will be triggered, necessitating the present fix.
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 25 Feb 2025 07:49:28 +0000
parents 6724fbb01a09
children
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 The present document is intended to be a guide for any parties who are going to
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 turn the present upstream gsm-codec-lib source package into user-friendly binary
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 packages for specific distributions.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4
456
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
5 Naming and attribution
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
6 ======================
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
7
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
8 Please note that the present GSM codec libraries and utilities suite should be
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
9 properly classified as Themyscira software and not FreeCalypso. Even though
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
10 FreeCalypso and Themyscira software realms currently have the same maintainer,
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
11 the two realms have different conventions that matter for packaging and
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
12 configuration management:
208
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13
456
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
14 * FreeCalypso software components are intended for users and tinkerers who work
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
15 with GSM phone handsets, GSM MS development boards, SIM cards and related
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
16 mobile-side hardware. That software realm uses a fixed /opt/freecalypso
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
17 directory hierarchy, non-FHS, which cannot be changed.
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
18
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
19 * Themyscira software components are intended to run on server machines where
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
20 they will often need to interwork closely with Osmocom and other network
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
21 software. Unlike FC, ThemWi software does _not_ require a fixed install
461
a53225b44ea5 further refinement of build system:
Mychaela Falconia <falcon@freecalypso.org>
parents: 456
diff changeset
22 location; at Themyscira HQ we use various custom directories under /opt for
a53225b44ea5 further refinement of build system:
Mychaela Falconia <falcon@freecalypso.org>
parents: 456
diff changeset
23 both Osmocom CNI and our own ThemWi components, but no one else is being
a53225b44ea5 further refinement of build system:
Mychaela Falconia <falcon@freecalypso.org>
parents: 456
diff changeset
24 asked to do what we do! We now follow the general free sw community standard
a53225b44ea5 further refinement of build system:
Mychaela Falconia <falcon@freecalypso.org>
parents: 456
diff changeset
25 whereby the default install location is /usr/local, but you are always free
a53225b44ea5 further refinement of build system:
Mychaela Falconia <falcon@freecalypso.org>
parents: 456
diff changeset
26 to change it to wherever you like with the standard --prefix option to
a53225b44ea5 further refinement of build system:
Mychaela Falconia <falcon@freecalypso.org>
parents: 456
diff changeset
27 configure.
456
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
28
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
29 Toward this end, all ThemWi software beginning with the present package will
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
30 have a ./configure script (hand-coded, no Autotools) that accepts the standard
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
31 --prefix option, allowing the install prefix to be chosen freely.
208
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32
456
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
33 Note that DESTDIR= setting on 'make install' is now supported! What is the
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
34 difference between --prefix argument to ./configure and DESTDIR= on the 'make
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
35 install' command? Answer: --prefix indicates the final location where the
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
36 software is meant to reside in its installed state, DESTDIR= is a local
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
37 modification for the 'make install' operation only, intended for staged installs
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
38 as happen in package build scripts.
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
39
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
40 Package splitting
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
41 =================
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
42
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
43 There are several different ways how the full GSM codec libraries and utilities
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
44 suite may be kept together or divided in binary packages:
208
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45
456
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
46 1) The simplest way is to have one binary package built from the source package,
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
47 containing all libraries and utilities.
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
48
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
49 2) The next option is to produce one package with libraries and a second package
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
50 with utilities. The utilities package will then depend on the libraries
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
51 package, but not the other way around.
208
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52
456
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
53 3) The finest division would be to produce a separate package for each codec
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
54 library (libgsmefr, libgsmfr2, libtwamr) and then a utilities package. The
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
55 set of utilities included in the present suite does not have clear-cut
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
56 logical divisions, hence it would probably make the most sense to have just
488
6724fbb01a09 PACKAGING: grammar fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 461
diff changeset
57 one utilities package that depends on all of the libraries.
456
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
58
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
59 The choice of approach is left to the discretion of individual packagers or
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
60 package maintainers.
208
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 Package versions
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 ================
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64
456
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
65 If separate packages are made for each codec library, these packages should be
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
66 versioned with their own proper semantic versions listed in the Library-versions
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
67 document, as opposed to the larger gsm-codec-lib tarball release version. If a
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
68 later gsm-codec-lib tarball release exhibits no changes in the libraries (the
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
69 only changes are in the command line utilities) or if only some of the libraries
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
70 exhibit changes (as indicated with a new semantic version), then NO new
208
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 downstream packages should be made for unchanged libraries - instead already
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 made binary packages for that library version (SemVer) should be retained.
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 Downstream package version numbers for command line utilities packages are up
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 to the discretion of packaging maintainers; using gsm-codec-lib tarball release
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 numbers is acceptable.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 Patience, please
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 ================
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 Please make downstream package releases *only* from officially published tarball
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 releases of gsm-codec-lib - please do *not* make packaged builds or "releases"
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 from our Mercurial repository. Any time we have a new development that is
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 expected to be useful to downstream end users, we shall make a proper tarball
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 release, and if there are any changes in the libraries, we shall assign new
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 semantic versions as appropriate.