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