docs/random/thomasvs/packaging - mtk-gstreamer - Git at Google

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