DOCS/tech/binary-packaging.txt

   1                 ________________________________________________
   2                  How to make good binary package(s) of MPlayer?
   3                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   4                        by Dominik 'Rathann' Mierzejewski
   5
   6 About this document
   7 ~~~~~~~~~~~~~~~~~~~
   8
   9 With the release of MPlayer 0.90pre9, all licensing issues have been
  10 eliminated and all code is licensed under the GPL, which allows
  11 independent packagers to create and distribute binary packages. At first,
  12 this was discouraged by some of the developers, but the users' demand for
  13 ready-to-use binary packages convinced some people to create them.
  14 Unfortunately, many currently available packages are crippled, include
  15 their own obsolete config files or are mispackaged in some other way. This
  16 document aims to establish a common set of packaging guidelines so that
  17 proper official binary packages for various Linux distributions and other
  18 operating systems can be maintained.
  19
  20
  21 Conventions
  22 ~~~~~~~~~~~
  23 Whenever you see "MUST", it means that following the mentioned guideline
  24 is required. Whenever you see "SHOULD", it means that following the
  25 guideline is highly recommended, but not required.
  26
  27
  28 Minimum feature set
  29 ~~~~~~~~~~~~~~~~~~~
  30 Due to MPlayer design, it is impossible to simply include all possible
  31 features and enable or disable them at runtime. That is why packagers
  32 SHOULD avoid "dependency hell" by retaining a reasonable, limited default
  33 feature set. After some discussion with other developers, we agreed that
  34 the following features MUST be included in any official binary package:
  35
  36 * audio/video output
  37   - fbdev
  38   - JPEG/PNG/TGA
  39   - (X)MGA
  40   - OSS
  41   - tdfxfb
  42   - (c/x)vidix
  43   - X11/Xvideo
  44
  45 * codecs
  46   - FAAD(internal)
  47   - libavcodec(internal)
  48   - native codecs (libmpeg2/liba52/mp3lib)
  49   - Vorbis Tremor codec(internal)
  50   - RealPlayer codecs support (*)
  51   - Win32/VfW/DShow/QT codecs support (*)
  52   - XAnim codecs support (*)
  53
  54 * general:
  55   - FreeType fonts support
  56   - HTML documentation
  57   - large file support
  58   - man page(s)
  59
  60 * input/demuxers:
  61   - DVD(libdvdread4/libdvdnav)
  62   - streaming
  63   - Matroska(internal)
  64   - (S)VCD
  65   - tv(v4l/v4l2)
  66
  67 (*) if available for your OS/hardware
  68
  69 There is great demand for the GUI, so it SHOULD be included, but it MUST
  70 come as a separate package (see Tips and Tricks for details).
  71
  72 Including other features, like LIVE.COM streaming or JACK support, is
  73 acceptable. They SHOULD, however, be build-time configurable, with the
  74 default build configuration containing the above set.
  75
  76 It seems there are some packages in the wild which lack included docs.
  77 This is VERY BAD, as it forces users to look for outside support when most
  78 of the common problems are easy to solve and are already described in the
  79 docs, thus increasing the number of repeated posts in MPlayer mailing
  80 lists. Binary packages MUST include both the man page and HTML
  81 documentation. Translated versions SHOULD be included, even if your
  82 package management system does not provide specific support for
  83 internationalization.
  84
  85 Libavcodec MUST always be in the latest development version and it SHOULD
  86 be linked statically into the mplayer binary, because MPlayer requires a
  87 recent libavcodec snapshot. It is acceptable to use a shared (again, recent)
  88 version of libavcodec, but you must be aware that this disables some of
  89 MPlayer's functions (for example, some postprocessing filters) and sacrifices
  90 speed.
  91
  92 Support for binary codecs SHOULD be present to the extent that the combination
  93 of operating system and CPU architecture permits, but it MUST NOT result in a
  94 hard dependency on a binary codecs package. MPlayer is fully functional without
  95 external binary codecs. If you package binary codecs yourself, package the
  96 essential codecs package, not the all codecs package.
  97
  98 Bitmap fonts are deprecated, don't package them. Use scalable (Type1/TrueType)
  99 fonts instead.
 100
 101
 102 File locations
 103 ~~~~~~~~~~~~~~
 104 In general, you SHOULD follow your distribution guidelines. For example,
 105 for Red Hat and Fedora RPMs I am using FHS-compliant paths:
 106
 107 /etc/mplayer/                   system-wide configs
 108 /usr/bin/                       binaries
 109 /usr/lib/codecs/                binary codecs
 110 /usr/lib64/codecs/              binary codecs on 64bit Linux
 111 /usr/share/doc/mplayer-version/ docs
 112 /usr/share/man/man1/            man page
 113 /usr/share/man/XX/man1/         translated man page
 114 /usr/share/mplayer/skins/       GUI skins
 115
 116 You MUST NOT include the codecs.conf file in your package. It is useful
 117 only for development purposes and often causes obscure problems for users.
 118
 119 Please avoid using the deprecated paths for binary codecs (/usr/lib/win32/)
 120 and skins (/usr/share/mplayer/Skin/).
 121
 122
 123 One package or many packages?
 124 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 125 Although it is tempting to simply provide a single all-in-one package,
 126 I think it is best to split MPlayer into several packages. It may be
 127 a little more troublesome for less clueful users, but it allows you to
 128 install only what you need. This is the layout I am using for Red Hat and
 129 Fedora RPMs:
 130
 131 mencoder         contains MEncoder binary (mencoder)
 132 mplayer          contains MPlayer binary without GUI (mplayer),
 133                  config files, man pages and documentation;
 134                  required by mplayer-gui
 135 mplayer-codecs-* contain binary codecs available from MPlayer's site
 136 mplayer-gui      contains MPlayer binary with GUI (gmplayer);
 137                  contains default skin (Blue)
 138 mplayer-skin-*   contain various MPlayer GUI skins
 139
 140 There is no strict policy for now, just use your common sense.
 141
 142
 143 Compilation
 144 ~~~~~~~~~~~
 145 While it is acceptable to provide packages optimized for specific CPUs,
 146 you MUST provide at least one "lowest common denominator" package set
 147 that will work on all CPUs. This means it MUST be configured with the
 148 --enable-runtime-cpudetection option. Building for specific CPUs requires
 149 disabling this option, but try to make sure that users cannot accidentally
 150 install a package not suitable for their CPU. With RPMs, for example, this
 151 is handled automatically, when building with the "--target arch" rpm option.
 152
 153 Compiler flags MUST be set to either configure-generated CFLAGS or something
 154 as close to them as possible.
 155
 156 Users MUST be able to rebuild your source package without hand-editing on
 157 any system with the same distribution installed. Remember to disable
 158 (--disable-xxx) any optional features, because MPlayer's configure script
 159 autodetects most of them. This ensures that binary package builds are
 160 deterministic -- that is, provided they have at least the required
 161 development packages installed, two different people using the same
 162 distribution will get binaries with the same dependencies.
 163
 164 You SHOULD provide an option to rebuild the package with full debug
 165 information enabled (by passing --enable-debug=3 to ./configure and
 166 disabling any stripping of binaries and libs during the build process).
 167 For example my source RPM can be rebuilt with a "--with debug" option, which
 168 does just that, making it easier to supply gdb information along with any
 169 bug reports, while retaining all benefits of using binary packages.
 170
 171
 172 Modifications
 173 ~~~~~~~~~~~~~
 174
 175 You MUST modify `mplayer -v` output so that it is clear that a user is
 176 using your binary package, by patching version.h and modifying the version
 177 string inside. Suggested convention is to include distribution name and,
 178 possibly, the signature of the packager or the repository. For example:
 179
 180 original:
 181  MPlayer 1.0pre5-3.3.2 (C) 2000-2004 MPlayer Team
 182 modified:
 183  MPlayer 1.0pre5-Fedora-GS-3.3.2 (C) 2000-2004 MPlayer Team
 184  MPlayer 1.0pre5-Mandrake-PLF-3.2.3 (C) 2000-2004 MPlayer Team
 185  MPlayer 1.0pre5-Solaris-3.4.0 (C) 2000-2004 MPlayer Team
 186
 187 If you patch MPlayer, send your patches to us! We will try to integrate them.
 188 Furthermore, we're often able to come up with a cleaner or more general
 189 solution to your problem.
 190
 191 If you have modified configuration files or similar, please patch the official
 192 one instead of copying it into your package. This way you will automatically
 193 pick up changes we make to it.
 194
 195 Do not override video and audio output selection in the system-wide config
 196 file. MPlayer will try to pick the best VO and AO itself and fall back
 197 gracefully. If you want to give priority to some AO, add a comma at the end
 198 of the line so that MPlayer can still fall back on others, for example:
 199 ao=alsa,
 200
 201 Tips and tricks
 202 ~~~~~~~~~~~~~~~
 203 In my package layout, mplayer and mplayer-gui can be installed at the same
 204 time, because they contain differently named binaries and there is no
 205 conflict. The trick is to build MPlayer once with --enable-gui, rename the
 206 resulting binary to "gmplayer" and then build it again, without GUI, but
 207 keeping the rest of ./configure options the same.
 208
 209 To provide man pages for all MPlayer suite binaries (mplayer, gmplayer,
 210 mencoder), you can use man-links instead of regular symbolic links.
 211 Creating a mencoder man page linked to mplayer is as simple as:
 212
 213   echo ".so mplayer.1" >> mencoder.1
 214
 215 A similar trick can be used for "man gmplayer". This avoids problems with
 216 gzipped man pages and symbolic links.
 217
 218 Newer Red Hat and Fedora distributions keep localized man pages encoded in
 219 UTF-8. If your distribution does the same, make sure you convert MPlayer's
 220 translated man pages to UTF-8 so that man mplayer works for locales other
 221 than English.