From ed58592fad085c1c0f3473a147c3d2834e60a52d Mon Sep 17 00:00:00 2001 From: Thomas Vander Stichele Date: Wed, 10 Mar 2004 13:45:38 +0000 Subject: [PATCH] packaging guidelines Original commit message from CVS: packaging guidelines --- docs/random/thomasvs/packaging | 162 +++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 docs/random/thomasvs/packaging diff --git a/docs/random/thomasvs/packaging b/docs/random/thomasvs/packaging new file mode 100644 index 0000000000..34c8e2e88e --- /dev/null +++ b/docs/random/thomasvs/packaging @@ -0,0 +1,162 @@ +Packaging guidelines for GStreamer +---------------------------------- + +Here are some guidelines for people trying to package GStreamer. + +VERSIONS +-------- + +First of all, there are two concepts of version in GStreamer. +The first is the source package version; it is either of the form +x.y.z or x.y.z.n + +x is the major number, y is the minor number, z is the micro number, and +n (if it exists) is the nano number. + +In the first case, it is an official release of GStreamer. +In the second case, it is a cvs version tarball if n == 1, and a prerelease +for the next version if n > 1. + +Source releases where y is even are considered "stable", and source releases +where y is uneven are considered "unstable" or "development". This is similar +to a lot of projects, including GLib and the kernel. + +The second version is an "interface" version, used in versioning tools, the +library name, packages, GConf install paths, registry locations, and so on. +It is of the form x.y +Commonly, it is refered to as the "major/minor" number of GStreamer. +In most cases it is the same as the one used in the source version; only +when we are doing release candidates for a new major/minor source version do +we manually force the major/minor to be the same as the one for the next +new version. This is done to shake out bugs that can arise due to this change +before we do an actual x.y.0 release. + +PARALLEL INSTALLABILITY +----------------------- +Versions of GStreamer with a different "interface" or major/minor version are +supposed to be parallel-installable. If they're not then it's considered to +be a bug. + +There are parallel-installable versions from the 0.6 set and onwards. + +In practice, this means that +- libraries contain the major/minor version in their name +- plugins are installed in a major/minor-versioned directory +- include headers are installed in separate directories +- registry is saved in major/minor-versioned locations +- major/minor-versioned tools are installed, together with versioned man pages +- non-versioned front-end tools are also installed, that call the + versioned ones, and only depend on glib and popt. + +So, all parts of GStreamer are parallel-installable, EXCEPT for the +non-versioned tools and man pages. However, only one of these sets needs +to be present, and preferably the latest source version of them. + +PACKAGING +--------- +To make packages of different major/minor versions parallel installable, the +important part is to separate the package of the nonversioned tools and +man pages, and make them usable for all the GStreamer library packages. + +We recommend putting the versioned binaries and man pages in the same package +as the base GStreamer library. + +The base GStreamer library should require a version of the non-versioned tools, +so that users can expect the non-versioned tools to be present in all cases, +and our documentation agrees with the install. + +As for package names, we recommend the following system: + +- "gstreamer" as the base name should be used for the latest stable version + of GStreamer. +- "gstreamerxy" should be used for all other versions (older stable version, + as well as current development version) + +As an example: + - 0.7 is current development version, and 0.6 is latest stable version: + "gstreamer" for 0.6 and "gstreamer07" for 0.7 + - 0.8.0 gets released: + "gstreamer06" for 0.6, "gstreamer07" is kept for 0.7, and + "gstreamer" for 0.8, where: + - the 0.8 "gstreamer" package can now obsolete the 0.7 package + - the 0.6 "gstreamer06" package can obsolete previous "gstreamer" packages + with lower version/release + +This ensures that users who just want the latest stable version of GStreamer +can just install the "gstreamer"-named set of packages, while automatic +tools can still upgrade cleanly, maintaining compatibility for applications +requiring older versions. + +This base named should be used for all GStreamer packages; +for example gstreamer07-plugins is a package of plugins to work with +the gstreamer07 base library package. + +SPLITTING OF PLUGIN PACKAGES +---------------------------- +Since GStreamer can depend on, but isn't forced to depend on, more than +40 additional libraries, choosing how to package these is a challenge +compared to other projects. + +Three approaches have been used in the past. One was "one package per +dependency library", so that users could choose exactly what functionality +they want installed. +A second one was "split according to functionality". This is more arbitrary. +A third one, used by some distributors, is "put everything we want to ship +in one big package". + +Packagers seem to agree that the first approach is too hard and users do not +care this much about fine-grained control. +We decided on a mix of 2) and 3); preferring to follow the base distribution's +decision for the base -plugins package, then creating additional packages +based on functionality. + +Plugins are put in -audio, -video, -dvd and -alsa packages. Also, some +plugins are put in -extras- packages because they are distributed from a +different location, are not as well maintained, have other issues, ... + +In the case of Fedora, for example, mp3 plugins are shipped in -extras-audio, +and distributed on FreshRPMS or rpm.livna.org +For Mandrake, for example, they would be shipped from PLF. + +Now, to make sure other packages can require functionality they need, +virtual provides are added for plugin packages, combining the base gstreamer +name with the name of the actual GStreamer plugin. + +Assuming 0.7, and the mad plugin, the package "gstreamer07-plugins-extra-audio" +would virtual-provide "gstreamer07-mad". It would contain the file +libgstmad.so in the correct directory. + +PACKAGING TIPS FOR RPMS +----------------------- +* use a define for the base package name for all GStreamer spec files: +%define gstreamer gstreamer07 +* use a define for the major/minor version of the package: +%define majorminor 0.7 + +This ensures you can easily migrate your spec files when a new major/minor +version is released. + +* always use the correctly versioned gst-register-x.y tool in post scripts + that install plugins. + It helps to create a define for this as well: +%define register %{_bindir}/gst-register-%{majorminor} > /dev/null 2>&1 + +* make each package that installs plugins have (pre) and (post) requires + on the versioned register binary + +* make each package that installs plugins have a requires on the corresponding + base plugins package + +* make sure that the nonversioned tools and man pages are put in a package + that is named "gstreamer-tools" no matter what the major/minor version is. + This way, the latest version of this package can be used for all previous + major/minor packages. If you do not want this package twice, with different + versions, then write your spec so that you don't package the tools for + previous versions, and only for the latest version. + +* applications that require specific plugins to function should require + the correct -plugins package, as well as any additional virtual provides + they need to pull in. + +* stable releases can obsolete: the previous development releases to ensure + they get removed when installing the new stable version.