			    ARDOUR README

			  Paul Barton-Davis

			     <pbd@op.net>

			    November 2000

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.sourceforge.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/libtool
system. If you are not, you should probably wait till binary releases
of Ardour emerge. 

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

Although Ardour uses the ALSA 0.6.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 are
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 its not my own primary focus.

To date, Ardour has only been run with:

   RME Hammerfall (Digi9652)            (26 channels in, 26 channels out)
   RME Hammerfall Light (Digi9636)      (18 channels in, 18 channels out)
   Hoontech 4Dwave-NX (Trident chipset) (2 channels in, 2/4 channels out)

Recording and playback work on the Hammerfalls.
Playback works on the trident card, and should work on any "consumer"
   audio interface (i.e. 16 bit, stereo-ish).
Recording has *not* been tested with any "consumer" interfaces.
Check it out, let me know what happens.

*** ice1712 chipsets (Midiman Delta series, and others):

This chipset has the interesting feature that the number of input
channels is not the same as the number of output channels. This
violates an assumption that ardour makes right now, and ardour will
not work. I intend to fix this in the near future, but I will need the
help of a user to do so, since I don't have this hardware.

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

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 its not a known bug.

1. COMPILING
------------

Compiling Ardour can be a little tricky, because it relies on a number
of still-under-development libraries. How you compile will depend on
whether you are using a source tarball, or CVS, and if the latter,
what you want to do about the independent libraries that Ardour uses.

Meanwhile, as detailed on the requirements page, please ensure that
before starting you have installed:

       ALSA 0.6.0 (CVS) 
       glib 1.2
       GTK+ 1.2
       Gtk-- 1.2
       Guile (I use 1.3.4)
       gcc/g++ 2.95.2 or above

You may also want to use libhoard, a very fast thread-friendly memory
allocator, but its not necessary. Use "configure --enable-hoard" if
you have it around.

1A: COMPILING FROM A SOURCE TARBALL
-----------------------------------

Unpack the source. Then do this:

       cd /where/i/put/the/ardour/source
       cd libs
       make
       cd ..
       ./configure
       make

1B. COMPILING FROM CVS
----------------------

The CVS tree is configured in a way that requires you to get 4 of my
libraries from the Quasimodo CVS repository. You will need to visit
http://quasimodo.org/ or http://quasimodo.sourceforge.net/, and use
CVS to checkout (at least):
    
    libpbd
    libmidi++
    libguileconfig
    libgtkmmext

Its probably easiest to just grab the whole of Quasimodo, though this
a lot of source :)

1B.1 - "I don't want to do a global install of the other libraries"
-------------------------------------------------------------------

Once you have checked out the libraries, DO NOT configure or compile them.
Instead, do this. Assume that $QM points to the location of the
Quasimodo source:

	 cd .../ardour/libs/src
	 ln -s $QM/libs/{pbd,midi++,guileconfig,gtkmmext} .
	 make

Assuming that this is successful, you can:

	 cd ..
	 sh ./autogen.sh
         configure
	 make

An annoying last step, which will eventually be fixed is:

         make install-guileDATA

And you're done:

         ./ardour

should start the program running.

1B.2 - "I want to do a global install of your other libraries"
-------------------------------------------------------------------

Do this (noting that the make install steps will likely require root
acces in order to be successful):

	cd /where/i/put/the/libpbd/source
	sh ./autogen.sh
	./configure --disable-static
	make
	make install

	cd /where/i/put/the/libmidi++/source
	sh ./autogen.sh
	./configure --disable-static
	make
	make install

	cd /where/i/put/the/libguileconfig/source
	sh ./autogen.sh
	./configure --disable-static
	make
	make install

	cd /where/i/put/the/libgtkmmext/source
	sh ./autogen.sh
	./configure --disable-static
	make
	make install

then:
   
	cd .../ardour
	mv libs libs-foo
	sh ./autogen.sh
	./configure
	make

An annoying last step, which will eventually be fixed is:

         make install-guileDATA

And you're done:

         ./ardour

should start the program running.

1A.3: "I don't want to deal with CVS for the other libraries"
-------------------------------------------------------------

It can be done. But its left as an exercise for the reader.


2. RUNNING ARDOUR
-----------------

You will need to:

2.1 Install the Ardour pixmaps

These provide the "theme" for Ardour. They are not part of the source
release, and they are not in CVS.  Fetch the latest release from
ardour.sourceforge.net (the project page), and install it. I put my
copy in a directory called "pixmaps" in the ardour source directory.

2.2 Set the ARDOURRC environment variable to point to your ardour
    configuration file. 

There is an example file in the source directory, called ardourrc.scm
(its the one I use myself). I hope that its sufficiently well
annotated that you will be able to create a modified version that
works for you. Just ask on ardour-dev if you have questions.

2.3 Setup your ALSA ~/.asoundrc file

Its very likely that you don't have this file yet. A sample is
included in the source directory, called "asoundrc". Copy it to your
home directory as ~/.asoundrc, and edit it to reflect your ALSA
configuration. Hopefully, this will become a standard part of ALSA
soon. 

2.4 Run ardour

If you have left the real-time options in the ardour config file as
they were, you will need to run ardour as root, since it needs root
priviledge to be able to to use SCHED_FIFO (realtime) scheduling.
  