FreeCalypso > hg > gsm-codec-lib

annotate PACKAGING @ 459:b094bc07051a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Codec-utils: document twamr-* addition
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 10 May 2024 19:50:29 +0000
parents 4c458145e793
children a53225b44ea5
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
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
22 location; the Mother's home environment uses /opt/themwi by default (although
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
23 even here we sometimes have to work with multiple installs like /opt/themwi2
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
24 etc), but the intent is that users of ThemWi software should have just as much
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
25 freedom to choose their install location as users of Osmocom CNI.
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
26
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
27 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
28 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
29 --prefix option, allowing the install prefix to be chosen freely.
208
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30
456
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
31 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
32 difference between --prefix argument to ./configure and DESTDIR= on the 'make
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
33 install' command? Answer: --prefix indicates the final location where the
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
34 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
35 modification for the 'make install' operation only, intended for staged installs
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
36 as happen in package build scripts.
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
37
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
38 Package splitting
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
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
41 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
42 suite may be kept together or divided in binary packages:
208
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43
456
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
44 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
45 containing all libraries and utilities.
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
46
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
47 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
48 with utilities. The utilities package will then depend on the libraries
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
49 package, but not the other way around.
208
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50
456
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
51 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
52 library (libgsmefr, libgsmfr2, libtwamr) and then a utilities package. The
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
53 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
54 logical divisions, hence it would probably make the most sense to have just
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
55 one utilities packages that depends on all of the libraries.
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
56
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
57 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
58 package maintainers.
208
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 Package versions
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
456
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
63 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
64 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
65 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
66 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
67 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
68 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
69 downstream packages should be made for unchanged libraries - instead already
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 made binary packages for that library version (SemVer) should be retained.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 Downstream package version numbers for command line utilities packages are up
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 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
74 numbers is acceptable.
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 Patience, please
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
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 Please make downstream package releases *only* from officially published tarball
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 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
81 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
82 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
83 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
84 semantic versions as appropriate.