annotate DOCS/tech/binary-packaging.txt @ 36313:0406e7c6f772

Revise switch_ratio documentation.

                ________________________________________________
                 How to make good binary package(s) of MPlayer?
                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                       by Dominik 'Rathann' Mierzejewski

About this document
~~~~~~~~~~~~~~~~~~~

With the release of MPlayer 0.90pre9, all licensing issues have been
eliminated and all code is licensed under the GPL, which allows
independent packagers to create and distribute binary packages. At first,
this was discouraged by some of the developers, but the users' demand for
ready-to-use binary packages convinced some people to create them.
Unfortunately, many currently available packages are crippled, include
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
proper official binary packages for various 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 not required.


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
  - tdfxfb
  - (c/x)vidix
  - X11/Xvideo

* codecs
  - libavcodec(internal)
  - RealPlayer codecs support (*)
  - Win32/VfW/DShow/QT codecs support (*)
  - XAnim codecs support (*)

* general:
  - FreeType fonts support
  - HTML documentation
  - large file support
  - man page(s)

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

(*) if available for your OS/hardware

There is great demand for the GUI, so it SHOULD be included, but it MUST
come as a separate package (see Tips and Tricks for details).

Including other features, like LIVE.COM streaming or JACK support, is
acceptable. They SHOULD, however, be build-time configurable, with the
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.

Libavcodec MUST always be in the latest development version and it SHOULD
be linked statically into the mplayer binary, because MPlayer requires a
recent libavcodec snapshot. It is acceptable to use a shared (again, recent)
version of libavcodec, but you must be aware that this disables some of
MPlayer's functions (for example, some postprocessing filters) and sacrifices
speed.

Support for binary codecs SHOULD be present to the extent that the combination
of operating system and CPU architecture permits, but it MUST NOT result in a
hard dependency on a binary codecs package. MPlayer is fully functional without
external binary codecs. If you package binary codecs yourself, package the
essential codecs package, not the all codecs package.

Bitmap fonts are deprecated, don't package them. Use scalable (Type1/TrueType)
fonts instead.


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

/etc/mplayer/                   system-wide configs
/usr/bin/                       binaries
/usr/lib/codecs/                binary codecs
/usr/lib64/codecs/              binary codecs on 64bit Linux
/usr/share/doc/mplayer-version/ docs
/usr/share/man/man1/            man page
/usr/share/man/XX/man1/         translated man page
/usr/share/mplayer/skins/       GUI skins

You MUST NOT include the codecs.conf file in your package. It is useful
only for development purposes and often causes obscure problems for users.

Please avoid using the deprecated paths for binary codecs (/usr/lib/win32/)
and skins (/usr/share/mplayer/Skin/).


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 Red Hat and
Fedora RPMs:

mencoder         contains MEncoder binary (mencoder)
mplayer          contains MPlayer binary without GUI (mplayer),
                 config files, man pages and documentation;
                 required by mplayer-gui
mplayer-codecs-* contain binary codecs available from MPlayer's site
mplayer-gui      contains MPlayer binary with GUI (gmplayer);
                 contains default skin (Blue)
mplayer-skin-*   contain various MPlayer GUI skins

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 the
--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 the "--target arch" rpm option.

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

Users MUST be able to rebuild your source package 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.

You SHOULD provide an option to rebuild the package with full debug
information enabled (by passing --enable-debug=3 to ./configure and
disabling any stripping of binaries and libs during the build process).
For example my source RPM can be rebuilt with a "--with debug" option, which
does just that, making it easier to supply gdb information along with any
bug reports, while retaining all benefits of using binary packages.


Modifications
~~~~~~~~~~~~~

You MUST modify `mplayer -v` output so that it is clear that a user is
using your binary package, by patching version.h and modifying the version
string inside. Suggested convention is to include distribution name and,
possibly, the signature of the packager or the repository. For example:

original:
 MPlayer 1.0pre5-3.3.2 (C) 2000-2004 MPlayer Team
modified:
 MPlayer 1.0pre5-Fedora-GS-3.3.2 (C) 2000-2004 MPlayer Team
 MPlayer 1.0pre5-Mandrake-PLF-3.2.3 (C) 2000-2004 MPlayer Team
 MPlayer 1.0pre5-Solaris-3.4.0 (C) 2000-2004 MPlayer Team

If you patch MPlayer, send your patches to us! We will try to integrate them.
Furthermore, we're often able to come up with a cleaner or more general
solution to your problem.

If you have modified configuration files or similar, please patch the official
one instead of copying it into your package. This way you will automatically
pick up changes we make to it.

Do not override video and audio output selection in the system-wide config
file. MPlayer will try to pick the best VO and AO itself and fall back
gracefully. If you want to give priority to some AO, add a comma at the end
of the line so that MPlayer can still fall back on others, for example:
ao=alsa,

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

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

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