This is the installation file for the Rivendell package.

PREREQUISITES
You will need the following installed and configured properly on your 
system before building Rivendell:

X11 Window System
Virtually all Linux distros should include this.

Qt Toolkit, v3.2 or better
Most modern Linux distros include this.  It's typically installed as part
of the KDE Desktop Environment, although KDE is by no means required.
It can also be downloaded directly from TrollTech (http://www.trolltech.com/).

Optionally, one or more audio driver libraries.  Choices are:

  AudioScience HPI Driver - v3.00 or greater.
  For supporting AudioScience's line of high-end professional audio adapters.  
  See http://www.audioscience.com/.

  The JACK Audio Connection Kit
  A low latency audio server, designed from the ground up for
  professional audio work.  See http://jackit.sourceforge.net/.
  Further information on running Rivendell with the JACK driver can be
  found in 'docs/JACK.txt'.

  The Advanced Linux Sound Architecture (ALSA) v1.0 or greater.
  The standard soundcard driver for Linux for kernels 2.6.x or later.
  See http://www.alsa-project.org/.

Secret Rabbit Code
A sample-rate converter library, written by Erik de Castro Lopo.  If
you are building support for JACK and/or ALSA, you will also need
this.  See http://www.mega-nerd.com/SRC/.

GPIO Driver
A kernel driver for the line of data-acquisition boards from 
MeasurementComputing.  See http://www.rivendellaudio.org/.

Cdda2Wav - CD Ripper Engine
Optional, but needed if you want the CD ripper to work.  Included in
most distributions, but also available from http://www.cdda2wav.de/.

CDParanoia - Another CD Ripper Engine
Optional, but needed if you want the CD ripper to work.  Needed in
order to support the full 'paranoia' mode of the CD ripper.  Included
in most distributions, but also available from
http://www.xiph.org/paranoia/.

SoX - Sound eXchange Universal Sound Sample Translator
Optional, but needed if you want the CD ripper or sound file importing
to work.  Included in most distributions, but also available from
http://sox.soundforge.net/.

bc - arbitrary precision calculator used when importing files to calculate 
normalisation levels. This is also included in most distributions and is 
available from ftp://ftp.gnu.org/pub/gnu/bc/ 

mySQL Database Server
Included in most Linux distributions.  See http://www.mysql.com/.

mpg321 - MPEG Audio Decoder.  Included in most Linux distributions.
See http://mpg321.sourceforge.net/.

Wget - Non-interactive network downloader.  Included with most distros,
or available from: http://www.gnu.org/software/wget/wget.html.

LFtp - Enhanced FTP client.  Included with most distros, or
available from: http://lftp.yar.ru/.

Samba Client - Utilities for working with SMB file shares.  Included
with most distros, or available from:  http://www.samba.org/.

Apache Web Server - Needed for the RDFeed RSS Podcast module.  Included with
most distros, or available from :  http://www.apache.org/.


INSTALLATION
There are three major steps to getting a Rivendell system up and
running.  They are:

1)  Setting up pre-requisite software

2)  Installing the Rivendell package

3)  Initial configuration

We'll cover each of these in turn.


1)  Setting Up Prerequisites

The major prerequisite piece of software needed for a functioning
Rivendell system is the mySQL database engine.  This needs to
be accessible from the target system (either by running on the local
host, or on a remote system) before Rivendell installation proper
is commenced.  In practice, this means that the 'mysqld' daemon is
running and can be connected to using the mysql(1) client.  You will
also need a login name/password for an account on the server with
administrative rights.

The process of configuring mySQL on a given host can be intricate and
is generally beyond the scope of this document.  Details can be found
in a number of books on the subject, as well as in the very extensive
documentation that accompanies the server itself.

If GPIO support is desired, this is also the time to install and test
the kernel GPIO driver. Full installation instructions as well as the 
list of currently supported GPIO boards are included in the package.


2)  Installing the Rivendell Package

Once the prerequisites are set up, installation is most often a matter of 
cd'ing to the top of the Rivendell source tree and typing
'./configure', 'make', followed (as root) by 'make install'.  Those
who obtained the source via CVS will need to do './autogen.sh' first.

The ./configure script will auto-detect what sound drivers (HPI, JACK
or ALSA) are available and enable build support accordingly.  To override
this behavior, it's possible to specify '--disable-hpi',
'--disable-jack' or '--disable-alsa' as an argument to './configure'.
Be sure to see the important additional information regarding
configuration in the 'docs/JACK.txt' or 'docs/ALSA.txt' files if you
plan on using those sound driver architectures.  If planning on using the RSS
Pocasting components, be sure to also read the section 'Web Components' below
regarding configuring placement of Rivendell's CGI scripts.


3)  Initial Configuration

Next, you'll need to install a small configuration file at
'/etc/rd.conf'.  A sample can be found in 'conf/rd.conf-sample'.  Much
of this can be used unchanged, with the exception of the entries in
the [Identity] section.  These should be changed to
reflect the user and group name of the system account that will be 
running Rivendell.

The directory for the audio sample data next needs to be created, as
so:

	mkdir /var/snd

This directory should owned, readable and writable by the user and
group specified in the 'AudioOwner=' and 'AudioGroup=' entires in
'/etc/rd.conf'.

Finally, it's time to start things up.  Run 'rdadmin' from a shell
prompt.  For the first time startup, RDAdmin will prompt for a login
name/password on the mySQL server so that it can create the Rivendell
database.  Once this has been done, and the main menu appears, be sure
to go into 'Manage Stations' and create an entry for the current 
workstation.

Much of the work in Rivendell gets done by three daemon processes,
named 'caed', 'ripcd' and 'rdcatchd'.  These daemons *must* be running
before attempting to start any of the Rivendell applications.  The
order in which they are started is important, and should be the same
as the order in which they are listed above.  For convienence, a Sys-V
style init script called 'rivendell' that can start, stop and restart 
the daemons properly is installed in '/etc/init.d/'.

When using the jackd audio connection system, it is important that jackd 
be up and running BEFORE the rivendell daemons are started. Really weird 
things happen if caed cannot connect to jack. 


4)  Web Components

The RDFeed script in Rivendell is installed in the directory specified by the
'--libexecdir=' parameter given to './configure' (default 'EPREFIX/bin').  The
proper location will vary widely on different distros according to how Apache
is installed.  On SuSE (assuming the default setup), the proper invocation is
'--libexecdir=/srv/www/rd-bin'.  Additionally, Apache must be configured
so as to allow CGI scripts with the file extension '.xml' to be executed in
the specified directory.  The './configure' script generates a code snippet
that can be included into the Apache configuration to accomplish this in 
'conf/rd-bin.conf'.


Good Luck!


Fred Gleason <fredg@paravelsystems.com>
