FreeCalypso > hg > gsm-codec-lib

annotate PACKAGING @ 483:4f13db3a7086

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Utils-overview: document new utilities
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 20 May 2024 01:26:12 +0000
parents a53225b44ea5
children 6724fbb01a09
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
4c458145e793 PACKAGING: new guidelines
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
57 one utilities packages that depends on all of the libraries.
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.