1Installation instructions for forked-daapd
2------------------------------------------
3
4There are two ways to install forked-daapd: from a tarball or from the git
5tree. The tarball contains a working build system and pre-generated ANTLR3
6parsers; the git tree doesn't and requires more tools to generate the build
7system and the ANTLR3 parsers.
8
9In both cases the installation procedure is the traditional ./configure;
10make; make install. Please read this file carefully before proceeding.
11
12
13System-specific requirements:
14 - Linux:
15   + glibc 2.9+ (for signalfd)
16   + libasound (ALSA sound support - or you can use OSS4)
17 - FreeBSD:
18   + OSS4 sound support
19   + libiconv
20
21Tools:
22 - pkg-config
23 - gperf 3.x
24        from <http://www.gnu.org/software/gperf/>
25
26Libraries:
27 - libantlr3c (ANTLR3 C runtime, version 3.2 for tarball builds)
28        from <http://www.antlr.org/download/C>
29 - Avahi client libraries (avahi-client), 0.6.24 minimum
30        from <http://avahi.org/>
31 - sqlite3 3.5.0+ with unlock notify API enabled (read below)
32        from <http://sqlite.org/download.html>
33 - libav 0.6+/0.7+ (or ffmpeg 0.5.1+)
34        from <http://libav.org/releases/>
35 - libconfuse
36        from <http://www.nongnu.org/confuse/>
37 - libevent 1.4+
38        from <http://www.monkey.org/~provos/libevent/>
39 - libavl
40        /!\ Read below
41 - MiniXML (aka mxml or libmxml)
42        from <http://minixml.org/software.php>
43 - gcrypt 1.2.0+
44        from <http://gnupg.org/download/index.en.html#libgcrypt>
45 - zlib
46        from <http://zlib.net/>
47 - libunistring 0.9.3+
48        from <http://www.gnu.org/software/libunistring/#downloading>
49 - libflac (optional - FLAC support)
50        from <http://flac.sourceforge.net/download.html>
51 - taglib (optional - Musepack support)
52        from <http://developer.kde.org/~wheeler/taglib.html>
53 - libplist 0.16+ (optional - iTunes XML support)
54        from <http://github.com/JonathanBeck/libplist/downloads>
55
56If using binary packages, remember that you need the development packages to
57build forked-daapd (usually named -dev or -devel).
58
59libavl is not the GNU libavl. There doesn't seem to be an upstream website
60anymore, but you'll find the source tarball alongside the forked-daapd
61release tarballs (see below for the URL). Alternatively, you can fetch it from
62any Debian mirror, too (it'll be in /debian/pool/main/liba/libavl).
63
64sqlite3 needs to be built with support for the unlock notify API; this isn't
65always the case in binary packages, so you may need to rebuild sqlite3 to
66enable the unlock notify API (you can check for the presence of the
67sqlite3_unlock_notify symbol in the sqlite3 library). Refer to the sqlite3
68documentation, look for SQLITE_ENABLE_UNLOCK_NOTIFY.
69
70
71Note about libav (ffmpeg)
72-------------------------
73
74libav (ffmpeg) is a central piece of forked-daapd and most other FLOSS
75multimedia applications. The version of libav you use will potentially have a
76great influence on your experience with forked-daapd.
77
78The following versions of libav (ffmpeg) are supported and known to work:
79 - ffmpeg 0.5.x: has issues with metadata (tags) extraction, notably with
80   MP3 files and ID3 tags in general;
81 - libav 0.6.x: known to work better with regard to metadata extraction;
82 - libav 0.7.x: better yet
83
84Note that forked-daapd uses libav since the ffmpeg/libav fork during the
850.6.x series.
86
87
88Building from the git tree
89--------------------------
90
91Gitweb: <http://git.debian.org/?p=users/jblache/forked-daapd.git>
92Git tree: <git://git.debian.org/users/jblache/forked-daapd.git>
93
94Required tools:
95 - ANTLR v3 is required to build forked-daapd, along with its C runtime
96   (libantlr3c). Use at least version 3.1.3 of ANTLR v3 and the matching
97   C runtime version.
98
99 - Java runtime: ANTLR is written in Java and as such a JRE is required to
100   run the tool. The JRE is enough, you don't need a full JDK.
101
102 - autotools: autoconf 2.63+, automake 1.10+, libtool 2.2. Run autoreconf -i
103   at the top of the source tree to generate the build system.
104
105 - gettext: libunistring requires iconv and gettext provides the autotools
106   macro definitions for iconv.
107
108Start by generating the build system by running autoreconf -i. This will
109generate the configure script and Makefile.in.
110
111The configure script will look for a wrapper called antlr3 in the PATH to
112invoke ANTLR3. If your installation of ANTLR3 does not come with such a
113wrapper, create one as follows:
114
115  #!/bin/sh
116  CLASSPATH=...
117  exec /path/to/java -cp $CLASSPATH org.antlr.Tool "@"
118
119Adjust the CLASSPATH as needed so that Java will find all the jars needed
120by ANTLR3.
121
122The parsers will be generated during the build, no manual intervention is
123needed.
124
125
126Building from the tarball
127-------------------------
128
129Download URL: <http://alioth.debian.org/~jblache/forked-daapd/>
130
131When building forked-daapd from a release tarball, the usual ./configure;
132make; make install procedure applies.
133
134FLAC and Musepack support are optional. If not enabled, metadata extraction
135will fail on these files.
136
137Support for iTunes Music Library XML format is optional. Use --enable-itunes
138to enable this feature.
139
140Recommended build settings:
141 ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --enable-flac --enable-musepack
142
143After installation, edit the configuration file, /etc/forked-daapd.conf and
144adjust the values at your convenience.
145
146forked-daapd will drop privileges to any user you'll specify in the
147configuration file if it's started as root. It's recommended to create a
148dedicated user without login privileges.
149
150This user must have read permission on your library (you can create a group for
151this and make the user a member of the group, for instance) and read/write
152permissions on the database location ($localstatedir/cache/forked-daapd by
153default).
154
155You'll need an init script if you want to start forked-daapd at boot. A simple
156init script will do, forked-daapd daemonizes all by itself and creates a
157pidfile under /var/run. Different distributions have different standards for
158init scripts and some do not use init scripts anymore; check the documentation
159for your distribution.
160
161For dependency-based boot systems, here are the forked-daapd dependencies:
162 - local filesystems
163 - network filesystems, if needed in your setup (library on NFS, ...)
164 - networking
165 - NTP
166 - Avahi daemon
167
168The LSB header below sums it up:
169
170### BEGIN INIT INFO
171# Provides:          forked-daapd
172# Required-Start:    $local_fs $remote_fs $network $time avahi
173# Required-Stop:     $local_fs $remote_fs $network $time
174# Default-Start:     2 3 4 5
175# Default-Stop:      0 1 6
176# Short-Description: media server with support for RSP, DAAP, DACP and AirTunes
177# Description:       forked-daapd is an iTunes-compatible media server for
178#                    sharing your music library over the local network with RSP
179#                    clients like the SoundBridge from Roku and DAAP clients like
180#                    iTunes. It can also stream music to AirTunes devices.
181### END INIT INFO
182