| 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. |