[MPlayer-DOCS] [RFC] Binary packaging guidelines

[Dominik 'Rathann' Mierzejewski]

Hello.

This is a more or less complete draft of my new Binary Packaging
Guidelines document which, as A'rpi was kind enough to remind me,
I promised to write a long time ago.

Please read and comment.

This will eventually be committed as DOCS/tech/binary-packaging.txt.

Regards,
R.

PS. TODO: version string changing and debug builds support

-- 
MPlayer RPMs maintainer: http://greysector.rangers.eu.org/mplayer/
"I am Grey. I stand between the candle and the star. We are Grey.
 We stand between the darkness ... and the light."
        -- Delenn in Grey Council in Babylon 5:"Babylon Squared"
-------------- next part --------------
                ________________________________________________
                 How to make good binary package(s) of MPlayer?
                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                       by Dominik 'Rathann' Mierzejewski
                                     (DRAFT)

About this document
~~~~~~~~~~~~~~~~~~~
With the release of MPlayer 0.90pre9 all licensing issues have been
eliminated and all code is licensed under the GPL. This allows creating
and distributing binary packages. Although this was discouraged by some of
the developers, the users' need for ready-to-use binary packages was
substantial and many packagers created them. Unfortunately, many of now
available packages are crippled, including their own obsolete config files
or are mispackaged in some other way. This document aims to establish a
common set of packaging guidelines so that official binary packages for
other Linux distributions and other operating systems can be maintained.


Conventions
~~~~~~~~~~~
Whenever you see "MUST", it means that following the mentioned guideline
is required. Whenever you see "SHOULD", it means that following the
guideline is highly recommended, but is not required, if necessary.


Minimum feature set
~~~~~~~~~~~~~~~~~~~
Due to MPlayer design, it is impossible to simply include all possible
features and enable or disable them at runtime. That is why packagers
SHOULD avoid "dependency hell" by retaining a reasonable, limited default
feature set. After some discussion with other developers, we agreed that
the following features MUST be included in any official binary package:

* audio/video output
  - fbdev
  - JPEG/PNG/TGA
  - (X)MGA
  - OSS 
  - SDL
  - tdfxfb
  - (c/x)vidix
  - X11/Xvideo/DGA

* codecs
  - FAAD(internal)
  - libavcodec
  - native codecs (libmpeg2/liba52/mp3lib)
  - Ogg Vorbis support
  - RealPlayer codecs support
  - Win32/VfW/DShow/QT codecs support
  - XAnim codecs support

* general:
  - default font
  - default skin (Blue)
  - FreeType fonts support
  - GUI
  - HTML documentation
  - large file support
  - man page(s)

* input/demuxers:
  - DVD(mpdvdkit2)
  - streaming
  - Matroska(internal)
  - (S)VCD
  - tv(v4l/v4l2)

Including other features, like LIVE.COM streaming or JACK support is
acceptable, but they SHOULD be build-time configurable, with default build
configuration containing the above set.

It seems there are some packages in the wild which lack included docs.
This is VERY BAD, as it forces users to look for outside support when most
of the common problems are easy to solve and are already described in the
docs, thus increasing the number of repeated posts in MPlayer mailing
lists. Binary packages MUST include both the man page and HTML
documentation. Translated versions SHOULD be included, even if your
package management system does not provide specific support for
internationalization.


File locations
~~~~~~~~~~~~~~
In general, you SHOULD follow your distribution guidelines. For RedHat and
Fedora RPMs I am using FHS-compliant paths:

/etc/mplayer/                   system-wide configs
/usr/bin/                       binaries
/usr/lib/codecs/                binary codecs
/usr/share/doc/mplayer-version/ docs
/usr/share/man/man1/            manpage
/usr/share/man/XX/man1/         translated manpage
/usr/share/mplayer/font/        fonts
/usr/share/mplayer/Skin/        GUI skins

NOTE: You MUST either make sure that /etc/mplayer/codecs.conf is always
in the latest available version or not provide that file at all.


One package or many packages?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Although it is tempting to simply provide a single all-in-one package, I
think it is best to split MPlayer into several packages. It may be a
little more troublesome for less clueful users, but it allows you to
install only what you need. This is the layout I am using for RedHat and
Fedora RPMs:

mencoder        contains MEncoder binary (mencoder)
mplayer         contains MPlayer binary without GUI (mplayer)
mplayer-codec-* contain binary codecs available from MPlayer's site
mplayer-common  contains config files, manpages and documentation;
                required by mplayer and mplayer-gui
mplayer-font-*  contain various bitmap fonts for OSD (obsolete)
mplayer-gui     contains MPlayer binary with GUI (gmplayer);
                requires at least one skin package
mplayer-skin-*  contain various MPlayer GUI skins
mplayer-vidix   contains vidix support library for MPlayer
mplayer-vidix-* contain vidix drivers for specific cards, one per package

Alternatively, one could include configs and docs in one package with
mplayer-gui and name it "mplayer" and provide additional package named
mplayer-nogui with the commandline version or the other way around.
There is no strict policy for now, just use your common sense.


Compilation
~~~~~~~~~~~
While it is acceptable to provide packages optimized for specific CPUs
You MUST provide at least one "lowest common denominator" package set
that will work on all CPUs. This means it MUST be configured with
--enable-runtime-cpudetection option. Building for specific CPUs requires
disabling this option, but try to make sure that users cannot accidentally
install a package not suitable for their CPU. With RPMs, for example, this
is handled automatically, when building with "--target arch" rpm option.

Compiler flags MUST be set to either configure-generated CFLAGS or something
as close to them as possible.

Make sure your source package can be rebuilt without hand-editing on any
system with the same distribution installed. Remember to disable
(--disable-xxx) any optional features, because MPlayer's configure script
autodetects most of them. This ensures that binary package builds are
deterministic. That is, provided they have at least the required development
packages installed, two different people using the same distribution will
get binaries with the same dependencies.


Tips and tricks
~~~~~~~~~~~~~~~
In my package layout, mplayer and mplayer-gui can be installed at the same
time, because they contain differently named binaries and there is no
conflict. The trick is to build MPlayer once with --enable-gui, rename the
resulting binary to "gmplayer" and then build it again, without GUI, but
keeping the rest of ./configure options the same.

To provide man pages for all MPlayer suite binaries (mplayer, gmplayer,
mencoder), you can use man-links instead of regular symbolic links.
Creating a mencoder man page linked to mplayer is as simple as:

  echo ".so mplayer.1" >> mencoder.1

Similar trick can be used for "man gmplayer". This avoids problems with
gzipped man pages and symbolic links.

Newer RedHat and Fedora distributions keep localized manpages encoded in
UTF-8. If your distribution does the same, make sure you convert MPlayer's
translated manpages to UTF-8 so that man mplayer works for locales other
than English.