------------------------------------------------------------------------------
                       H Y D R O G E N          Drum machine
------------------------------------------------------------------------------

BUILDING AND INSTALLING HYDROGEN
================================

Contents:

1. System Requirements
2. Download
3. Binary Packages
4. Prerequisites to Build from Source
5. Build and Install from Source
6. INSTALL.txt Changelog

1. System Requirements
----------------------

Hydrogen is supported on the following operating systems:

  * Linux/Unix/BSD
  * Mac OS X

Hydrogen is *not* supported on Windows because there are currently no
Windows developers on the project... and so the Windows components
have fallen into disrepair.

Hydrogen is known to work well on fairly old systems like this (as of
2009):

  Pentium III 500 MHz
  198 MB RAM
  Consumer-Grade (cheap) audio card
  Keyboard and Mouse
  1x1 USB MIDI Interface (optional)

2. Download
-----------

Hydrogen can be downloaded as a binary package, source distribution,
or you can check out the current development version with Subversion.
These can be accessed on the Hydrogen home page:

	http://www.hydrogen-music.org/

The source code for the current development version can be checked out
via Subversion:

	$ svn co http://svn.assembla.com/svn/hydrogen/trunk hydrogen

3. Binary Packages
------------------

Debian (GNU/Linux) and Ubuntu (GNU/Linux):

	Hydrogen can usually be installed with apt:

	# apt-get install hydrogen

	However, if you wish to have a more current version of
	Hydrogen, the Hydrogen dev's typically maintain a .deb package
	for Debian stable, testing, and some Ubuntu distributions.
	Note that apt takes care of any library dependencies that you
	have.

Other GNU/Linux:

	Check your package management system for the package
	'hydrogen.'

Mac OS X:

	They Hydrogen home page has a binary package available for OS
	X.  Extract the ZIP archive and it will create a hydrogen.app
	folder.

4. Prerequisites to Build from Source
-------------------------------------

In order to build from source, you will need the following libraries
installed on your system, and the development header files:

	REQUIRED
	* Qt 4 Library (>=4.4.0, 4.3.x might work, 4.2.x won't)
	* Qt 4 SDK (moc, uic, etc.)
	* GNU g++ compiler (>=4.0, 3.x might work)
	* scons (>=0.98, 1.0 preferred, <0.98 might work)
	* libsndfile >=1.0.17
	* zlib and libtar -OR- libarchive
	  OS X: You will probably need to build libarchive from source.
	* At least 1 audio and 1 midi driver
	* OS X: Xcode

	DRIVERS AVAILABLE
	* JACK Audio Connection Kit (>=0.103.0)
	* ALSA (Advanced Linux Sound Architecture)
	* OSS
	* PortAudio (v18, not v19)
	* PortMIDI
	* CoreAudio (OS X)
	* CoreMidi (OS X)

	OPTIONAL SUPPORT
	* LASH (Linux Audio Session Handler)
	* libFLAC for handling FLAC sound files.
	* liblrdf for LADSPA plugins

On a single, 500MHz processor Hydrogen takes about 1.5 hours to build.

5. Build and Install from Source
--------------------------------

If you wish to build a package for your operating system, skip down to
the end of this section.

This instructions are thought for building hydrogen on linux.
We're providing a set of qmake project files for windows and
mac osx builds. 
Please read the relevant wiki pages for more informations:

http://trac.assembla.com/hydrogen/wiki/development%3AcompileOSX
http://trac.assembla.com/hydrogen/wiki/coding%3Apackagingwin

After you have all the prerequisites, building and installing will
look like this:

	$ tar xjf hydrogen-0.9.4.tar.bz2
	$ cd hydrogen-0.9.4
	$ scons
	$ sudo scons install

If you wish to configure features like LADSPA plugins, FLAC support,
or debugging symbols, get more information like this:

	$ scons --help

To change the directory where scons is installed, it is done like
this:

	$ scons prefix=/path/to/install/dir
	$ sudo scons install

Uninstalling Hydrogen is done like this:

	$ sudo scons -c install

Note that scons is a build system and not a package manager.  While we
make every effort to ensure that Hydrogen uninstalls cleanly, it is
not a guarantee.

Hydrogen uses a scons tool that detects the correct Qt settings, but
sometimes it needs a little help.  If Hydrogen fails to build
(typically when a .ui file fails), set the Qt 4 install directory like
this:

	$ QTDIR=/opt/lib/qt4 scons

It's also best to ensure that your PATH is pointing to the Qt 4
versions of moc and uic, and not the Qt 3 versions.

___CREATING A BINARY PACKAGE___

If you are a package maintainer and wish for your packaging scripts to
be included in the Hydrogen source tree, we would be happy to work
with you.  Please contact the developer mailing list (see the Hydrogen
home page).  The instructions below are for the package systems that
have been contributed so far.

___CREATING A .DEB PACKAGE___

In order to create a .deb package for Debian or Debian-based systems
(like Ubuntu), you first need the debhelper package:

	# apt-get install debhelper

To build the Hydrogen package:

	$ tar xjf hydrogen-0.9.4.tar
	$ cd hydrogen-0.9.4
	$ cd linux
	$ fakeroot dpkg-buildpackage

This will place the .deb package and description files in the parent
directory.  If you wish to change the version number for the archive,
edit linux/debian/changelog to set the version.

6. INSTALL.txt Changelog
------------------------

2009-04-08 Gabriel M. Beddingfield <gabriel@teuton.org>
	* Create INSTALL.txt