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/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 Including other features, like LIVE.COM streaming or JACK support, is
  70 acceptable. They SHOULD, however, be build-time configurable, with the
  71 default build configuration containing the above set.
  72
  73 It seems there are some packages in the wild which lack included docs.
  74 This is VERY BAD, as it forces users to look for outside support when most
  75 of the common problems are easy to solve and are already described in the
  76 docs, thus increasing the number of repeated posts in MPlayer mailing
  77 lists. Binary packages MUST include both the man page and HTML
  78 documentation. Translated versions SHOULD be included, even if your
  79 package management system does not provide specific support for
  80 internationalization.
  81
  82 Libavcodec MUST always be in the latest development version and it SHOULD
  83 be linked statically into the mplayer binary, because MPlayer requires a
  84 recent libavcodec snapshot. It is acceptable to use a shared (again, recent)
  85 version of libavcodec, but you must be aware that this disables some of
  86 MPlayer's functions (for example, some postprocessing filters) and sacrifices
  87 speed.
  88
  89 Support for binary codecs SHOULD be present to the extent that the combination
  90 of operating system and CPU architecture permits, but it MUST NOT result in a
  91 hard dependency on a binary codecs package. MPlayer is fully functional without
  92 external binary codecs. If you package binary codecs yourself, package the
  93 essential codecs package, not the all codecs package.
  94
  95 Bitmap fonts are deprecated, don't package them. Use scalable (Type1/TrueType)
  96 fonts instead.
  97
  98
  99 File locations
 100 ~~~~~~~~~~~~~~
 101 In general, you SHOULD follow your distribution guidelines. For example,
 102 for Red Hat and Fedora RPMs I am using FHS-compliant paths:
 103
 104 /etc/mplayer/                   system-wide configs
 105 /usr/bin/                       binaries
 106 /usr/lib/codecs/                binary codecs
 107 /usr/lib64/codecs/              binary codecs on 64bit Linux
 108 /usr/share/doc/mplayer-version/ docs
 109 /usr/share/man/man1/            man page
 110 /usr/share/man/XX/man1/         translated man page
 111
 112 You MUST NOT include the codecs.conf file in your package. It is useful
 113 only for development purposes and often causes obscure problems for users.
 114
 115 Please avoid using the deprecated paths for binary codecs (/usr/lib/win32/)
 116 and skins (/usr/share/mplayer/Skin/).
 117
 118
 119 One package or many packages?
 120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 121 Although it is tempting to simply provide a single all-in-one package,
 122 I think it is best to split MPlayer into several packages. It may be
 123 a little more troublesome for less clueful users, but it allows you to
 124 install only what you need. This is the layout I am using for Red Hat and
 125 Fedora RPMs:
 126
 127 mencoder         contains MEncoder binary (mencoder)
 128 mplayer          contains MPlayer binary config files, man pages and
 129                  documentation;
 130 mplayer-codecs-* contain binary codecs available from MPlayer's site
 131
 132 There is no strict policy for now, just use your common sense.
 133
 134
 135 Compilation
 136 ~~~~~~~~~~~
 137 While it is acceptable to provide packages optimized for specific CPUs,
 138 you MUST provide at least one "lowest common denominator" package set
 139 that will work on all CPUs. This means it MUST be configured with the
 140 --enable-runtime-cpudetection option. Building for specific CPUs requires
 141 disabling this option, but try to make sure that users cannot accidentally
 142 install a package not suitable for their CPU. With RPMs, for example, this
 143 is handled automatically, when building with the "--target arch" rpm option.
 144
 145 Compiler flags MUST be set to either configure-generated CFLAGS or something
 146 as close to them as possible.
 147
 148 Users MUST be able to rebuild your source package without hand-editing on
 149 any system with the same distribution installed. Remember to disable
 150 (--disable-xxx) any optional features, because MPlayer's configure script
 151 autodetects most of them. This ensures that binary package builds are
 152 deterministic -- that is, provided they have at least the required
 153 development packages installed, two different people using the same
 154 distribution will get binaries with the same dependencies.
 155
 156 You SHOULD provide an option to rebuild the package with full debug
 157 information enabled (by passing --enable-debug=3 to ./configure and
 158 disabling any stripping of binaries and libs during the build process).
 159 For example my source RPM can be rebuilt with a "--with debug" option, which
 160 does just that, making it easier to supply gdb information along with any
 161 bug reports, while retaining all benefits of using binary packages.
 162
 163
 164 Modifications
 165 ~~~~~~~~~~~~~
 166
 167 You MUST modify `mplayer -v` output so that it is clear that a user is
 168 using your binary package, by patching version.h and modifying the version
 169 string inside. Suggested convention is to include distribution name and,
 170 possibly, the signature of the packager or the repository. For example:
 171
 172 original:
 173  MPlayer 1.0pre5-3.3.2 (C) 2000-2004 MPlayer Team
 174 modified:
 175  MPlayer 1.0pre5-Fedora-GS-3.3.2 (C) 2000-2004 MPlayer Team
 176  MPlayer 1.0pre5-Mandrake-PLF-3.2.3 (C) 2000-2004 MPlayer Team
 177  MPlayer 1.0pre5-Solaris-3.4.0 (C) 2000-2004 MPlayer Team
 178
 179 If you patch MPlayer, send your patches to us! We will try to integrate them.
 180 Furthermore, we're often able to come up with a cleaner or more general
 181 solution to your problem.
 182
 183 If you have modified configuration files or similar, please patch the official
 184 one instead of copying it into your package. This way you will automatically
 185 pick up changes we make to it.
 186
 187 Do not override video and audio output selection in the system-wide config
 188 file. MPlayer will try to pick the best VO and AO itself and fall back
 189 gracefully. If you want to give priority to some AO, add a comma at the end
 190 of the line so that MPlayer can still fall back on others, for example:
 191 ao=alsa,
 192
 193 Tips and tricks
 194 ~~~~~~~~~~~~~~~
 195 To provide man pages for all MPlayer suite binaries (mplayer, mencoder), you
 196 can use man-links instead of regular symbolic links.
 197 Creating a mencoder man page linked to mplayer is as simple as:
 198
 199   echo ".so mplayer.1" >> mencoder.1
 200
 201 A similar trick can be used for "man gmplayer". This avoids problems with
 202 gzipped man pages and symbolic links.
 203
 204 Newer Red Hat and Fedora distributions keep localized man pages encoded in
 205 UTF-8. If your distribution does the same, make sure you convert MPlayer's
 206 translated man pages to UTF-8 so that man mplayer works for locales other
 207 than English.