Add stuff to the README.Debian file describing differences

with the official Debian package. Also add instruction for
enabling Wayland support on Debian testing/unstable
(the only place it natively works).

1 files changed, 97 insertions, 8 deletions

diff --git a/debian/README.debian b/debian/README.debian
index d6292e5..49eb194 100644
--- a/debian/README.debian
+++ b/debian/README.debian
@@ -1,15 +1,104 @@
 mpv for Debian
---------------
+==============
 
-  You can build the package using 'debuild -uc -us -b -j<number of jobs>'.
+This is the Debian package produced by the mpv-build scripts. It
+contains a statically linked libass and ffmpeg (vs. libav contained in
+Debian) from upstream. It is not an official part of the Debian
+distribution. Instructions for building this package can be found in
+the README.rst file in the mpv-build directory, or equivalently at [1].
 
--- Wessel Dankers <wsl@fruit.je>, Sun, 06 Jan 2013 13:44:11 +0100
+[1] https://github.com/mpv-player/mpv.
 
-  libx264 and libmp3lame are already enabled. To enable
-  non-free codecs, install libfdk-aac-dev and add the options to the
-  mpv-build/ffmpeg_options file
+Differences with the official Debian package
+============================================
+
+Debian testing/unstable already has a separate official package for
+mpv, which closely tracks the current upstream releases. The biggest
+difference between this package and the one in the official Debian
+archive is that it statically links against the latest upstream
+version of ffmpeg and libass. Debian uses the libav fork of ffmpeg,
+and therefore that's what the official package links against. However,
+as described at [2], ffmpeg is preferred for building mpv. The version
+of libass in Debian unstable also has a slight lag behind the current
+upstream release used to build this package.
+
+[2] https://github.com/mpv-player/mpv/wiki/FFmpeg-versus-Libav
+
+Furthermore, the official Debian mpv package is ONLY available in
+unstable/testing. It will in general not work in Debian stable (there
+is currently no version in backports) or in any current release of
+Ubuntu. This package on the other hand, builds and installs on both Debian
+stable, and testing/unstable as well as Ubuntu precise (12.04) and saucy
+(13.10). For the older distributions, this package is probably the best
+alternative.
+
+In order to maintain this interoperability between distributions, this
+package must necessarily disable some features by default which are
+not universally supported. This includes decoding with libmpg123 (as
+opposed to the decoders built into ffmpeg), sdl2 audio output, and
+Wayland video support (which may nevertheless still be enabled
+manually provided sufficiently recent libraries - see below). On the
+other hand, this package enables video4Linux and native samba support
+(to play smb:// URLs), which are not present in the official Debian
+package.
+
+There are several other features that are disabled in both this
+package as well as the official Debian package because they are not
+widely needed or used. These include caca, radio interface, openal
+output, portaudio output, rsound/libroar/sndio input/output, sdl1,
+joystick, videoio.h/libpt. If you find any of these useful, please
+open an issue at [3] explaining why you think the feature in question
+should be enabled, and we can try and include it in this package.
+
+[3] https://github.com/mpv-player/mpv-build/issues
+
+Finally, in addition to the default of building the latest released
+version of mpv, this package can also trivially be built from the
+latest git master of mpv (as well as ffmpeg and libass). As described
+in README.rst [1], this is achieved by calling
+
+    ./update --master 
+
+prior to building this Debian package.
+
+Non-free encoding codecs
+========================
+
+The optional encoding libraries libx264 and libmp3lame are already
+enabled by this package. To enable additional non-free codecs,
+manually install Fraunhofer FDK AAC codec development files 
+
+    apt-get install libfdk-aac-dev
+
+and add the relevant options to the mpv-build/ffmpeg_options file
 
-    echo --enable-libfdk-aac >> ffmpeg_options
     echo --enable-nonfree    >> ffmpeg_options
+    echo --enable-libfdk-aac >> ffmpeg_options
+
+This must be done prior to building this package.
+
+Wayland support
+===============
+
+According to wayland.freedesktop.org, "Wayland is intended as a
+simpler replacement for X, easier to develop and maintain". It is very
+much a work in progress, so adequate functionality requires recent
+version of the relevant libraries. At present, this is only possible
+on Debian testing/unstable (not stable or Ubuntu precise or saucy). To
+maintain interoperability, this package therefore does not build with
+Wayland support by default.
+
+If you want Wayland support, you will need to manually install the
+necessary packages before building:
+
+    apt-get install libwayland-dev libxkbcommon-dev
+
+The mpv build will then automatically detect and link to them.
+
+Note that for mpv=0.3.4, you need 
+
+    libwayland-dev>=1.2.0, libxkbcommon-dev>=0.3.0,
+
+while for mpv in git master, you need
 
--- Kevin Mitchell <kevmitch@gmail.com>  Wed, 29 Jan 2014 19:21:44 -0800
+    libwayland-dev>=1.3.0, libxkbcommon-dev>=0.3.0