owntone-server/INSTALL

Installation instructions for forked-daapd
------------------------------------------

This document contains instructions for installing forked-daapd from the git
tree.

The source for this version of forked-daapd can be found here:

  <https://github.com/ejurgensen/forked-daapd.git>

The original (now unmaintained) source can be found here:

  <http://git.debian.org/?p=users/jblache/forked-daapd.git>


Quick version for Debian/Ubuntu users
-------------------------------------

If you are the lucky kind, this should get you all the required tools and
libraries:

sudo apt-get install \
 build-essential git autotools-dev autoconf libtool gettext gawk gperf \
 antlr3 libantlr3c-dev libconfuse-dev libunistring-dev libsqlite3-dev \
 libavcodec-dev libavformat-dev libswscale-dev libavutil-dev libasound2-dev \
 libmxml-dev libgcrypt11-dev libavahi-client-dev libavl-dev zlib1g-dev \
 libevent-dev

Depending on the version of libav/ffmpeg in your distribution you may also need
libavresample-dev.

To build with LastFM support, you should also install libcurl4-openssl-dev.

Note that while forked-daapd will work with versions of libevent between 2.0.0
and 2.1.3, it is recommended to use either libevent 1 or 2.1.4+. Otherwise you
will not have support for Shoutcast metadata and simultaneous streaming to
multiple clients. Libevent 1 is not in the Debian repository, but you can get
the packages in the Ubuntu repository.

Then run the following:

 git clone https://github.com/ejurgensen/forked-daapd.git
 cd forked-daapd
 autoreconf -i
 ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var
 make
 sudo make install

Finally, read the bit in the bottom of this document about init scripts, read
the README, edit the configuration file and restart the server.


Quick version for FreeBSD 10+
-----------------------------

The build process for FreeBSD is rather complicated, but the good news is that
there is a script in the 'scripts' folder that will at least attempt to do all
the work for you. And should the script not work for you, you can still look
through it and use it as an installation guide.


Long version - requirements
---------------------------

System-specific requirements:
 - Linux:
   + glibc 2.9+ (for signalfd)
   + libasound (ALSA sound support - or you can use OSS4)
 - FreeBSD:
   + OSS4 sound support
   + libiconv


Required tools:
 - ANTLR v3 is required to build forked-daapd, along with its C runtime
   (libantlr3c). Use a version between 3.1.3 and 3.4 of ANTLR v3 and the
   matching C runtime version. Get it from <http://www.antlr3.org/>

 - Java runtime: ANTLR is written in Java and as such a JRE is required to
   run the tool. The JRE is enough, you don't need a full JDK.

 - autotools: autoconf 2.63+, automake 1.10+, libtool 2.2. Run autoreconf -i
   at the top of the source tree to generate the build system.

 - gettext: libunistring requires iconv and gettext provides the autotools
   macro definitions for iconv.

 - gperf


Libraries:
 - libantlr3c (ANTLR3 C runtime, use the same version as antlr3)
        from <https://github.com/antlr/website-antlr3/tree/gh-pages/download/C>
 - Avahi client libraries (avahi-client), 0.6.24 minimum
        from <http://avahi.org/>
 - sqlite3 3.5.0+ with unlock notify API enabled (read below)
        from <http://sqlite.org/download.html>
 - libav 0.6.x - 0.8.x (or ffmpeg 0.5.x - 0.10.x)
        from <http://libav.org/releases/>
 - libconfuse
        from <http://www.nongnu.org/confuse/>
 - libevent 1.4+ (best with version 1.4 or 2.1.4+)
        from <http://libevent.org/>
 - libavl 0.3.5
        from <http://ftp.debian.org/debian/pool/main/liba/libavl>
 - MiniXML (aka mxml or libmxml)
        from <http://minixml.org/software.php>
 - gcrypt 1.2.0+
        from <http://gnupg.org/download/index.en.html#libgcrypt>
 - zlib
        from <http://zlib.net/>
 - libunistring 0.9.3+
        from <http://www.gnu.org/software/libunistring/#downloading>
 - libflac (optional - FLAC support)
        from <http://flac.sourceforge.net/download.html>
 - taglib (optional - Musepack support)
        from <http://developer.kde.org/~wheeler/taglib.html>
 - libplist 0.16+ (optional - iTunes XML support)
        from <http://github.com/JonathanBeck/libplist/downloads>
 - libspotify (optional - Spotify support)
        from <https://developer.spotify.com>
 - libcurl (optional - LastFM support)
        from <http://curl.haxx.se/libcurl/>

If using binary packages, remember that you need the development packages to
build forked-daapd (usually named -dev or -devel).

libavl is not the GNU libavl. There doesn't seem to be an upstream website
anymore, but you can fetch it from any Debian mirror.

sqlite3 needs to be built with support for the unlock notify API; this isn't
always the case in binary packages, so you may need to rebuild sqlite3 to
enable the unlock notify API (you can check for the presence of the
sqlite3_unlock_notify symbol in the sqlite3 library). Refer to the sqlite3
documentation, look for SQLITE_ENABLE_UNLOCK_NOTIFY.

libav (or ffmpeg) is a central piece of forked-daapd and most other FLOSS
multimedia applications. The version of libav you use will potentially have a
great influence on your experience with forked-daapd.

forked-daapd is known to be working with libav 0.8.x, but it also supports older
versions of libav and ffmpeg.

Embedded artwork is only supported if your version of forked-daapd is built
with libav 9+ or ffmpeg 0.11+.


Long version - building and installing
--------------------------------------

Start by generating the build system by running autoreconf -i. This will
generate the configure script and Makefile.in.

The configure script will look for a wrapper called antlr3 in the PATH to
invoke ANTLR3. If your installation of ANTLR3 does not come with such a
wrapper, create one as follows:

  #!/bin/sh
  CLASSPATH=...
  exec /path/to/java -cp $CLASSPATH org.antlr.Tool "@"

Adjust the CLASSPATH as needed so that Java will find all the jars needed
by ANTLR3.

The parsers will be generated during the build, no manual intervention is
needed.

To display the configure options run ./configure --help

Support for Spotify is optional. Use --enable-spotify to enable this feature.
If you enable this feature libspotify/api.h is required at compile time.
Forked-daapd uses runtime dynamic linking to the libspotify library, so even
though you compiled with --enable-spotify, the executable will still be able
to run on systems without libspotify (the Spotify features will then be 
disabled).

Support for LastFM scrobbling is optional. Use --enable-lastfm to enable this
feature.

Support for iTunes Music Library XML format is optional. Use --enable-itunes
to enable this feature.

FLAC and Musepack support are optional, and they are probably only required
if your version of libav/ffmpeg is very old (version 0.5 or 0.6). Use
--enable-flac and --enable-musepack to enable.

Recommended build settings:
 ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var

After configure run the usual make, and if that went well, sudo make install


Long version - after installation
---------------------------------

After installation, edit the configuration file, /etc/forked-daapd.conf and
adjust the values at your convenience.

forked-daapd will drop privileges to any user you'll specify in the
configuration file if it's started as root.

This user must have read permission on your library (you can create a group for
this and make the user a member of the group, for instance) and read/write
permissions on the database location ($localstatedir/cache/forked-daapd by
default).

You'll need an init script if you want to start forked-daapd at boot. A simple
init script will do, forked-daapd daemonizes all by itself and creates a
pidfile under /var/run. Different distributions have different standards for
init scripts and some do not use init scripts anymore; check the documentation
for your distribution.

For dependency-based boot systems, here are the forked-daapd dependencies:
 - local filesystems
 - network filesystems, if needed in your setup (library on NFS, ...)
 - networking
 - NTP
 - Avahi daemon

The LSB header below sums it up:

### BEGIN INIT INFO
# Provides:          forked-daapd
# Required-Start:    $local_fs $remote_fs $network $time
# Required-Stop:     $local_fs $remote_fs $network $time
# Should-Start:      avahi
# Should-Stop:       avahi
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: DAAP/DACP (iTunes) server, support for AirPlay and Spotify
# Description:       forked-daapd is an iTunes-compatible media server for
#                    sharing your media library over the local network with DAAP
#                    clients like iTunes. Like iTunes, it can be controlled by
#                    Apple Remote (and compatibles) and stream music directly to
#                    AirPlay devices. It also supports streaming to RSP clients
#                    (Roku devices) and streaming from Spotify.
### END INIT INFO