From Gentoo Wiki
Jump to: navigation, search

Maintainer notes about xine-lib package and its relatives.



This guide was last updated for media-libs/xine-lib version 1.1.8

media-libs/xine-lib is the package that carries the core of xine video player. Differently from media-video/mplayer that is a standalone program, xine frontends uses libxine to play video files. This has the disadvantages that a crash inside libxine shows up as a crash of the frontend itself, and that the included copies of libraries might end up in symbols' collisions if they aren't taken care correctly.

For this reason the media-libs/xine-lib package must be managed carefully, to avoid adding dangerous crashes that might be difficult to reproduce (the same happened in the past). As in many cases the crashes are difficult to grasp just looking at the code, as there might be symbols collisions and similar stuff, to report bugs it's important to produce also a valid backtrace of the crash.

Here you'll find a lot of "why and how" about media-libs/xine-lib and related packages like media-video/xine-ui, media-video/gxine and so on. Hopefully, this guide will be updated during the time, also when maintainer changes.

To contact developers of the xine project, you can also use the #xine channel hosted on FreeNode.


media-libs/xine-lib used to be heavy patched on Portage tree; although the original reason was because of automagic dependencies, there were patches and fixes for those external projects (likeffmpeg orvidix ) that weren't being applied by upstream.

Since version 1.1.2 the patchset is heavily reduced, also because the former maintainer (Pettenò Diego Pettenò) is now contributing directly to xine project . For this reason, while he's present, it's a good idea to pass through him for patches that are needed.

Since 1.1.4 version, the only patch needed is part of the old TEXTREL patch; this patch is missing up to now.

If a patch that is not Gentoo-specific is being added to the ebuild, is usually suggested to send it upstream through their tracker, to be applied upstream. Similarly bugs that are not Gentoo specific are to be reported there so that they can be fixed directly by upstream. Backporting patches is an option once upstream fixed the issue.

The preferred method to receive patches by the xine project is to send them as Mercurial exports: commit them on a local clone of the repository, and then use hg export to prepare the patch to send. This way the original author of the patch will be listed in the log.

As media-libs/xine-lib uses a number of libraries that are synced from time to time with its source tree, the patches that changes files imported from other projects are usually not accepted by media-libs/xine-lib's upstream and needs to be sent to the originating project. The main examples are ffmpeg and vidix , but also dvdnav . In those cases, if the patch is applied upstream, it might be usefult to ask for a sync of the sources to xine's developers.

The patches are hosted in CVS inside gentoo/src/patchsets/xine-lib and are organized by version. Released patchsets are tagged with the name of the tarball minus the .tar.bz2 . The directories contains also a series file, as they are used by quilt: just symlink the checked out directory inside an extracted source tree of xine-lib (for that version) and use quilt to manage the patches.

Also if usually this point was never stressed out, now that patches are hosted on the CVS it's important that they bring a description in the header, with also a link to relevant bugs, both in Gentoo and upstream.

External and internal libraries

As many other multimedia programs, also media-libs/xine-lib has dependencies on a lot of libraries for format input and output. Most of them are optional, and some of them are included inside the same source tarball as the library.

The patches used in the past to use external libraries instead of internals are now (as of 1.1.1 version of media-libs/xine-lib) included in the original sources. The use of external libraries is enabled passing --with-external- library to the configure script. It's preferred to use the external libraries (Portage-provided) so that if they need to be fixed, xine will make use of the fixes. This was for example the case of libmad decoding library on 64-bit systems.

As also libmad is used external or not used at all, media-libs/xine-lib might not be always able to decode mp3 audio without it. Since version 1.1.2_pre20060328-r1 this doesn't lead to crashes any longer. Since version 1.1.3_pre20060929, even with mad useflag disabled MP3 files can be decoded through FFmpeg (albeit with some problems).

An exception to the above rules applies to libdvdnav . The internal version in xine-lib is a CVS snapshot of the copy developed by the Linux DVD project, and thus works better than the last released copy. xine-lib 1.1 is not yet ready to use the new version developed by MPlayer project.

Although in the past ffmpeg support was selectable between internal and external through the ffmpeg useflag, starting from media-libs/xine-lib 1.1.2 the only choice is to use the external copy. This makes simpler the ebuild, requires messing less with the code to build PIC safe code, and reduces the amount of TEXTRELs that are created. Updating media-libs/xine-lib for newer snapshots of ffmpeg might be required, but that should be done before its actual unmasking.

Older ebuilds had to do some tricks to get the path for X libraries such as libXv and libXvMC, as the default configure script didn't take the right libraries when looking for them in the usual places. This is now solved as the ebuilds depend on modular XOrg, and upstream configure now uses pkg-config for libraries discovery.

There also was a problem using three different XvMC libraries. Since version 1.1.3_pre20060929, the xvmc USE flag uses the XvMCW wrapper library rather than choosing at build time one of the three libraries.


As many other multimedia programs, also media-libs/xine-lib has its own problems with extremely riced flags. Actually, the original xine-lib configure uses by itself quite extreme flags, on x86 and amd64 platforms. A saner behaviour can be applied by using the --disable-optimizations option at ./configure .

In the past we had to force a few optimisations on to be able to build media-libs/xine-lib on x86, but as we now use the external copy of FFmpeg libraries, most of the problems are solved and now xine-lib can be built fine without much tinkering.


media-libs/xine-lib uses quite a few useflags. Almost every dependency has its own useflag to enable or disable it. The useflags works basically as every other useflag with the same name in other packages, but there are a couple that have notes.

The first note is about win32codecs useflag. This is used to enable the support for the binary win32 codecs that are emulated using a subset of Wine functions. Since version 1.1.3 onward, as xine-lib supports decoding of WMV9 files through ffmpeg. The ASF demuxer is now forced enabled.

A note about the debug useflag is probably good; this useflag was added after request in bug #112980, and just adds -UNDEBUG -DDEBUG to the flags passed to compiler. media-libs/xine-lib has a way to create a "debug build" by using special make targets, this build simply adds -DDEBUG -g flags to the compiler flags. Using that with debug useflag is bad looking inside the ebuild. The -g flag should be passed by the user if he really wants debug data, so the only thing ad hoc for the package is the -DDEBUG flag. If you want to be able to get meaningful backtraces, please follow the related guide.

Talking about the flac flag, instead, it's useful to know that it does not control the ability of media-libs/xine-lib to decode FLAC files: it simply enables or disables the libFLAC-based decoder and demuxer, both of which are not mandatory, as there's a native FLAC demuxer in xine-lib, and FFmpeg can decode FLAC files just fine without this flag enabled.

The TEXTRELs issue

media-libs/xine-lib, along with other multimedia software, has problems related to TEXTRELs in compiled binaries on x86 platform. The problem is stated in bug #113255.

Thanks to the PaX Team, xine-lib-1.1.1-r3 and later versions are now fixed not to have TEXTRELs due to the win32codecs support and to the postprocessing filters of xine itself.

As ffmpeg is now always used external, all the issues inside this package are now fixed, and the remaining ones are actually up to ffmpeg itself.

The patch was mostly merged into xine-lib CVS since before the 1.1.4 release, with the exception of some TomSoComp changes that seems to cause crashes with some interlaced media when SSE is enabled; that is the only missing patch up to now.

Live Development Snapshots

Missing an updated release after 1.1.1, and this having quite a few of problems (counting in also a security issue), it happened that a pre-1.1.2 snapshot was made and also marked stable. In case there will be need for more snapshots, these are the basic instructions needed to generate one.

The first thig is to get a Mercurial checkout of xine-lib sources from the proper branch. At the moment xine-lib is developed using Mercurial at Alioth, and the branch you're interested to is most likely the 1.1 branch Make sure it is complete and not with a lot of FIXME in the log. After that you can use the simple command make dist to build a tarball to use for the ebuild. Make sure you try a make distcheck to ensure that everything is present, and run a few compile tests as well as runtime tests so that it works.

Patches has to be applied over that snapshot, not included in the snapshot itself, to make sure they don't collide if they have to be modified. The patches can be handled as usual from Gentoo CVS with quilt .

The snapshot tarball, the directory inside it and the patches directory should be all named using ${P} variable, and the tarball should be compressed with bzip2



media-video/xine-ui is considered the main xine frontend, as it's released by the same project as media-libs/xine-lib and it is toolkit-agnostic.

Its handling is much simpler than media-libs/xine-lib's, patches and bugs can still be sent upstream through xine's tracker, and then dropped when the new releases are done.

In a fashion similar to media-libs/xine-lib, also patches to media-video/xine-ui are hosted in CVS at gentoo/src/patchsets/xine-ui, orderd by version. The directories are also quilt patches so they can be symlinked and then managed by it. It's important to document the non-obvious patches, as done for xine-lib.

Missing a 0.99.5 release, and having the previous one security issues, there's currently in the tree also a snapshot version that fixes a lot of stability issues, as well as a few security problems. The new 0.99.5 version should solve all the previous issues.


media-video/gxine is a frontend based on GTK2 toolkit, it has fewer optional dependencies than media-video/xine-ui so it's usually simpler to manage. Although it had a few security vulnerabilities in the past, the new code should be safer. Patches to this can be sent to xine's tracker as usual or to the upstream maintainer, Darren Salt. As per xine-lib, the patches are welcome as Mercurial commits exports.

Like xine-lib, gxine is developed in a Mercurial repository at Alioth, you probably want to get the branch .

Of the few useflags, the only one that requires a bit of handling is nsplugin , that is used to build and install the Mozilla plugin.


media-video/kaffeine is a KDE application that used to be a media-libs/xine-lib frontend, while at the moment it supports not only xine, but also mplayer and gstreamer KParts . Xine remains the main engine and it's the only mandatory one.

Its handling is usually in KDE herd's hands, as most of the problems that might arise with it are related to media-libs/xine-lib itself. The only important detail to remember is that it requires a newer xorg-x11 as there were troubles with old versions and with xfree .

Kaffeine can use XCB library for xine video output, through the xcb USE flag, which requires xcb USE flag to be enabled in media-libs/xine-lib too. Upstream wants soon to make this a default non-switchable behaviour as without XCB, Kaffeine's embedding through KPart will make GwenView, Konqueror and other software crash at unload.


We would like to thank the following authors and editors for their contributions to this guide:

  • Diego Pettenò