Debian Codegraph @

docs/random/thomasvs/packaging

raw
1 Packaging guidelines for GStreamer
2 ----------------------------------
3
4 Here are some guidelines for people trying to package GStreamer.
5
6 VERSIONS
7 --------
8
9 First of all, there are two concepts of version in GStreamer.
10 The first is the source package version; it is either of the form
11 x.y.z or x.y.z.n
12
13 x is the major number, y is the minor number, z is the micro number, and
14 n (if it exists) is the nano number.
15
16 In the first case, it is an official release of GStreamer.
17 In the second case, it is a cvs version tarball if n == 1, and a prerelease
18 for the next version if n > 1.
19
20 Source releases where y is even are considered "stable", and source releases
21 where y is uneven are considered "unstable" or "development". This is similar
22 to a lot of projects, including GLib and the kernel.
23
24 The second version is an "interface" version, used in versioning tools, the
25 library name, packages, GConf install paths, registry locations, and so on.
26 It is of the form x.y
27 Commonly, it is referred to as the "major/minor" number of GStreamer.
28 In most cases it is the same as the one used in the source version; only
29 when we are doing release candidates for a new major/minor source version do
30 we manually force the major/minor to be the same as the one for the next
31 new version. This is done to shake out bugs that can arise due to this change
32 before we do an actual x.y.0 release.
33
34 PARALLEL INSTALLABILITY
35 -----------------------
36 Versions of GStreamer with a different "interface" or major/minor version are
37 supposed to be parallel-installable. If they're not then it's considered to
38 be a bug.
39
40 There are parallel-installable versions from the 0.6 set and onwards.
41
42 In practice, this means that
43 - libraries contain the major/minor version in their name
44 - plugins are installed in a major/minor-versioned directory
45 - include headers are installed in separate directories
46 - registry is saved in major/minor-versioned locations
47 - major/minor-versioned tools are installed, together with versioned man pages
48 - non-versioned front-end tools are also installed, that call the
49 versioned ones, and only depend on glib and popt.
50
51 So, all parts of GStreamer are parallel-installable, EXCEPT for the
52 non-versioned tools and man pages. However, only one of these sets needs
53 to be present, and preferably the latest source version of them.
54
55 PACKAGING
56 ---------
57 To make packages of different major/minor versions parallel installable, the
58 important part is to separate the package of the nonversioned tools and
59 man pages, and make them usable for all the GStreamer library packages.
60
61 We recommend putting the versioned binaries and man pages in the same package
62 as the base GStreamer library.
63
64 The base GStreamer library should require a version of the non-versioned tools,
65 so that users can expect the non-versioned tools to be present in all cases,
66 and our documentation agrees with the install.
67
68 As for package names, we recommend the following system:
69
70 - "gstreamer" as the base name should be used for the latest stable version
71 of GStreamer.
72 - "gstreamerxy" should be used for all other versions (older stable version,
73 as well as current development version)
74
75 As an example:
76 - 0.7 is current development version, and 0.6 is latest stable version:
77 "gstreamer" for 0.6 and "gstreamer07" for 0.7
78 - 0.8.0 gets released:
79 "gstreamer06" for 0.6, "gstreamer07" is kept for 0.7, and
80 "gstreamer" for 0.8, where:
81 - the 0.8 "gstreamer" package can now obsolete the 0.7 package
82 - the 0.6 "gstreamer06" package can obsolete previous "gstreamer" packages
83 with lower version/release
84
85 This ensures that users who just want the latest stable version of GStreamer
86 can just install the "gstreamer"-named set of packages, while automatic
87 tools can still upgrade cleanly, maintaining compatibility for applications
88 requiring older versions.
89
90 This base named should be used for all GStreamer packages;
91 for example gstreamer07-plugins is a package of plugins to work with
92 the gstreamer07 base library package.
93
94 SPLITTING OF PLUGIN PACKAGES
95 ----------------------------
96 Since GStreamer can depend on, but isn't forced to depend on, more than
97 40 additional libraries, choosing how to package these is a challenge
98 compared to other projects.
99
100 Three approaches have been used in the past. One was "one package per
101 dependency library", so that users could choose exactly what functionality
102 they want installed.
103 A second one was "split according to functionality". This is more arbitrary.
104 A third one, used by some distributors, is "put everything we want to ship
105 in one big package".
106
107 Packagers seem to agree that the first approach is too hard and users do not
108 care this much about fine-grained control.
109 We decided on a mix of 2) and 3); preferring to follow the base distribution's
110 decision for the base -plugins package, then creating additional packages
111 based on functionality.
112
113 Plugins are put in -audio, -video, -dvd and -alsa packages. Also, some
114 plugins are put in -extras- packages because they are distributed from a
115 different location, are not as well maintained, have other issues, ...
116
117 In the case of Fedora, for example, mp3 plugins are shipped in -extras-audio,
118 and distributed on FreshRPMS or rpm.livna.org
119 For Mandrake, for example, they would be shipped from PLF.
120
121 Now, to make sure other packages can require functionality they need,
122 virtual provides are added for plugin packages, combining the base gstreamer
123 name with the name of the actual GStreamer plugin.
124
125 Assuming 0.7, and the mad plugin, the package "gstreamer07-plugins-extra-audio"
126 would virtual-provide "gstreamer07-mad". It would contain the file
127 libgstmad.so in the correct directory.
128
129 PACKAGING TIPS FOR RPMS
130 -----------------------
131 * use a define for the base package name for all GStreamer spec files:
132 %define gstreamer gstreamer07
133 * use a define for the major/minor version of the package:
134 %define majorminor 0.7
135
136 This ensures you can easily migrate your spec files when a new major/minor
137 version is released.
138
139 * always use the correctly versioned gst-register-x.y tool in post scripts
140 that install plugins.
141 It helps to create a define for this as well:
142 %define register %{_bindir}/gst-register-%{majorminor} > /dev/null 2>&1
143
144 * make each package that installs plugins have (pre) and (post) requires
145 on the versioned register binary
146
147 * make each package that installs plugins have a requires on the corresponding
148 base plugins package
149
150 * make sure that the nonversioned tools and man pages are put in a package
151 that is named "gstreamer-tools" no matter what the major/minor version is.
152 This way, the latest version of this package can be used for all previous
153 major/minor packages. If you do not want this package twice, with different
154 versions, then write your spec so that you don't package the tools for
155 previous versions, and only for the latest version.
156
157 * applications that require specific plugins to function should require
158 the correct -plugins package, as well as any additional virtual provides
159 they need to pull in.
160
161 * stable releases can obsolete: the previous development releases to ensure
162 they get removed when installing the new stable version.