			    ARDOUR README

		Paul Davis <pbd@op.net> November 2002

Welcome to Ardour.  This program is still very much under development,
but has now reached the stage where it will be productive and useful
to have other people testing it out and perhaps (hopefully!) fixing
bugs and adding features.

Please: before you do anything else, take a moment to go and join the
ardour-dev mailing list (members only).  It is very important that the
community of people using, testing and developing this software are on
the list, and I will NOT deal with questions relating to Ardour's
compilation or bugs that are not sent to that list.  See
http://ardour.sf.net/ for details on joining the mailing
list.

This document is written for an audience that is familiar with
compiling software that uses the GNU automake/autoconf system.  If you
are not, you should probably wait till binary releases of Ardour
emerge. 

**** SECURITY *******************************************************

To run Ardour with the lowest latencies, it's necessary to use POSIX
Real-Time Scheduling as well as locking all the memory it uses into
physical RAM.  These requirements can only be met if Ardour is run with
root priviledges. 

On the other hand, things are not so bad.  If you don't attempt to
install it setuid root (which actually won't work anyway), then
someone needs to have gained root access in order to run it like this.
If they already have root access, Ardour is the least of your
problems.  So relax.  We'll use capabilities once Linux kernels start
arriving with them enabled, though this won't help too much with
security, since the relevant capabilities would still allow a wiley
cracker to do anything at all.

Alternatively, you can choose to run Ardour without RT scheduling, and
then there's no concern at all.  It just won't be useful in low latency
situations, which are desirable in most studio environments. Note that
this is not so important if you have audio hardware that is capable of 
doing "hardware monitoring" - in this case, a lack of low latency will
simply make response to Ardour's UI controls a little sluggish, but
monitoring during capture will be excellent.

**** HARDWARE COMPATIBILITY *****************************************

Although Ardour uses the ALSA 0.9.0 API, it exercises this API in a
way that no other application to date has done, and it also tries to
use certain hardware features that again, no other existing
applications use.  As a result, although complete portability to all
ALSA supported h/w is an eventual and very achievable goal, there may
be issues surrounding h/w compatibility.  Please remember that my
primary goal with Ardour is to build a professional quality HDR
system.  If it happens to be useful for people with 2/4 channel cards,
then great, but it's not my own primary focus.

One other important issue is that your audio interface must support
full duplex i/o with the same sample format for both capture and
playback.  This means, for example, that the SoundBlaster AWE cannot be
used with Ardour - it only supports full duplex i/o if one of the two
directions (capture or playback) is 8 bit and the other is 16.  Very
few cards have this kind of limitation, and if they do, they typically
are not suitable for use with applications like Ardour for other
reasons.

To date, Ardour has been run with:

   RME Hammerfall (Digi9652)              (26 channels in, 26 channels out)
   RME Hammerfall Light (Digi9636)        (18 channels in, 18 channels out)
   Midiman Delta series (ice1712 chipset) (12 channels in, 10 channels out)
  
   Various consumer grade audio interfaces, typically with 2 channels
   in, 2/4 channels out, including:
   
   Hoontech 4Dwave-NX (Trident chipset)
   Ensoniq 5880
   Soundblaster 32
   Soundblaster 64
   Creative SBLive64

So, basically, it appears to work for just about all ALSA supported
cards, which is the goal.
  
**********************************************************************

0. BUG REPORTING
----------------

Bug reports will only be given any attention when sent to the
ardour-dev mailing list.  Please read the file "TODO" before sending a
bug report, to ensure that it's not a known bug.

1) GNU AUTOCONF RATIONALIZATION
-------------------------------
 
GNU autoconf is a clever system, but it has at least one major flaw.
By default, autoconf (actually, aclocal) looks in only ONE directory
for files that it needs.  That might be OK, except that when other
software packages are installed, they sometimes put their autoconf
files in /usr/local/lib/share/aclocal and sometimes in
/usr/lib/share/aclocal.

As a result, autoconf often cannot find the files it needs to build
Ardour, since many people have a mixture of libraries installed from
source (autoconf files typically ended up in /usr/local/lib...) and from
pre-built packages (autoconf files typically ended up on /usr/lib...).

So, for the sake of your sanity, I recomend taking the the following
step as root.  Please check the contents of both directories before
doing this "merge" so that you don't accidentally wipe out the correct
version of a duplicated autoconf file:

 * If you have both directories:

    cd /usr/lib/share/aclocal
    cp *.m4 /usr/local/lib/share/aclocal
    cd ..
    rm -rf aclocal
    ln -s /usr/local/lib/share/aclocal .

 * If you have only /usr/lib/share/aclocal

    cd /usr/local/lib
    ln -s /usr/lib/share/aclocal .

Some distributions have aclocal in a different place.  YMMV. 

2. COMPILING
------------

Please ensure that before attempting to compile Ardour, you have
installed:

* Tools:

       gcc/g++ 2.95.3 or above (gcc/g++ 3.x works also) 
       autoconf 2.52 or above
       automake 1.5 or above
       libtool 1.4.2 or above
	   gettext 0.11.5 or above
       pkgconfig 0.8.0 or above 
	   		http://www.freedesktop.org/software/pkgconfig/
	   
	   lex and yacc are also required.

* Libraries:

Recommended versions, where applicable, are shown under the general
requirement. 

       ALSA 0.9.X (CVS or snapshot release) (http://www.alsa-project.org)

       JACK (CVS release) (http://jackit.sourceforge.net)

       glib 1.2   (http://www.gtk.org)
	glib-1.2.8 (included with most distributions)

       GTK+ 1.2   (http://www.gtk.org)
	gtk+-1.2.8 (included with most distributions)

       libsndfile (http://www.zip.com.au/~erikd/libsndfile)
	libsndfile-1.0 or higher

       libsamplerate (http://www.mega-nerd.com/SRC/)
         libsamplerate 0.0.13 or higher

       gdbm (http://www.gnu.org/software/gdbm)
        any recent version

       the LADSPA SDK (http://www.ladspa.org/)
	(See below)
       
If you have an SMP system, you may also want to use libhoard, a very
fast thread-friendly memory allocator, but it's not necessary.  Use
"./configure --enable-hoard" if you have it around.
(http://www.cs.utexas.edu/users/emery/hoard/)

Getting LADSPA

Note: the LADSPA SDK really only consists of a header file, and you
can get that like this (all one line):

  lynx -dump http://www.ladspa.org/ladspa_sdk/ladspa.h.txt > \
           /usr/local/include/ladspa.h

However, you may want the plugins that come with it, so go ahead and
download the whole package (it's not big), install the header, build
the plugins and install them too.

I would also recommend getting Steve Harris' excellent set of LADSPA
plugins from http://plugin.org.uk/.  They make Ardour into a truly
useful application.  Other LADSPA plugins will be appearing - be sure
to watch the Linux Audio Development mailing list for announcements.

2A) COMPILING FROM CVS
---------------------

Checkout the source from Ardour CVS (the `%' here is meant to be your
shell prompt):

% cd /usr/local/src    # just an example, it can be anywhere
% cvs -d:pserver:anonymous@cvs.ardour.sf.net:/cvsroot/ardour login
                       # (just press enter/return when prompted for a password)
% cvs -d:pserver:anonymous@cvs.ardour.sf.net:/cvsroot/ardour -z3 co ardour

Now build the autoconf/automake files:

% cd ardour
% sh autogen.sh

Now proceed to step 3.

2B) COMPILING FROM A TARBALL
----------------------------

As usual, fetch and unpack the tarball.  The directory it creates,
ardour-<version>, is referred to below as "$AD".

3) HOW TO COMPILE
-----------------

    ./configure
    make
    make install

As usual with configure scripts, if you don't want the installation to
happen in the "usual place", add a --prefix option to ./configure.

Compilation takes a while.  Running with make -j3 on a dual PII-450,
the entire build takes about 10-15 minutes.

**********************************************************************

4. RUNNING ARDOUR
-----------------

You will need to:

4.1 Install the Ardour pixmaps

These provide the "theme" for Ardour.  They are not in CVS, but they
are available as part of the source tarballs/packages and as a
separate tarball.  Fetch the latest release from ardour.sf.net and
install it.  I put my copy in a directory called "pixmaps" in the
Ardour source directory.

4.2 Setup your ALSA ~/.asoundrc file

It's quite likely that you don't have this file yet.  Here is a
sample for a machine with a single audio interface:

pcm.myname {
   type hw
   card 0
}

ctl.myname {
   type hw
   card 0
}

For more help on the contents of this file, please use the ALSA
mailing lists, not the ardour-dev mailing list or myself.

4.3 Set the ARDOUR_SYSTEM_RC environment variable to point to your Ardour
    configuration file, and ***** EDIT THAT FILE ******.

4.4 Set the ARDOURRC environment variable to point to your Ardour
    configuration file, and ***** EDIT THAT FILE ******.

There are example files in the top of the source tree, called
ardour_system.rc and ardour.rc (they're the ones I use myself).  I
hope that it's sufficiently obvious that you will be able to create
modified versions that works for you.  Just ask on ardour-dev if you
have questions.

NB.  The sfdb option specifies a file not a directory.  It is a gdbm file 
that stores basic information about soundfiles it discovers when it is 
told to search certain directories.

4.5 Run Ardour

You must have a running JACK server before starting Ardour.

If you ran "make install", then then typing "ardour" at this point
will hopefully have some effect. "ardour --help" lists available
options.

If you did not run "make install", then use "ardev" from the directory
in which you built the GTK interface for ardour. 

