Copyright (c) 2006-2013 Sylvain Joyeux <[email protected]> and contributors

* http://rock-robotics.org

This work is licensed under the BSD license. See License.txt for details

== What's autobuild ?
Autobuild imports, configures, builds and installs various kinds of software packages.
It can be used in software development to make sure that nothing is broken in the 
build process of a set of packages, or can be used as an automated installation tool.

Autobuild config files are Ruby scripts which configure rake to
* imports the package from a SCM or (optionnaly) updates it
* configures it. This phase can handle code generation, configuration (for
  instance for autotools-based packages), ...
* build
* install

It takes the dependencies between packages into account in its build process,
updates the needed environment variables (+PKG_CONFIG_PATH+, +PATH+,
+LD_LIBRARY_PATH+, ...)


== WARNING for 0.5 users
Old configuration files used with autobuild 0.5 aren't accepted by Autobuild
0.6. Since 0.6, Autobuild uses Ruby for configuration (just like rake does)

== Available packages
=== Common usage
All package objects define the following attributes
*importer*:: the importer object (see "Available importers" below)
*srcdir*:: where the package sources are located. If it is a relative
	   path, it is relative to the value of Autobuild.srcdir. The default is to
	   use the package name. 
*prefix*:: the directory where the package should be installed. If it is a relative
	   path, it is relative to the value of Autobuild.prefix. The default is to
	   use the package name. 

Each package method (Autobuild.import, Autobuild.autotools, ...) takes either a package
name for first argument, or a <tt>name => dependency_array</tt> hash, and take a block which
can be used to configure the package. For instance
    Autobuild.import :my_package do |pkg|
	pkg.srcdir = 'my_package_dir'
    end

    Autobuild.import :my_package => [:depends, :depends_also] do |pkg|
    end

=== Source only
    package = Autobuild.import(dependencies) do |pkg|
	<package configuration>
    end

Use +import+ if you need the package sources but don't need to build it. You just need
to set +importer+ and +srcdir+. +prefix+ is ignored.

=== Autotools
    package = Autobuild.autotools(name, dependencies) do |pkg|
	<package configuration>
    end

Use this to build GNU autotools-based packages. This handles autoconf-only packages as 
well as those using automake

Options to give the +configure+ script are given in the +configureflags+ array
    pkg.configureflags = ['--with-blah', 'FOO=bar' ]

If you want the files produced during the build to be separated from the source files, set the +builddir+ attribute.
For now, it has to be a relative path, relative to the source directory.
    pkg.builddir = 'build'

The generation of the configure script uses four programs: +autoheader+, +autoconf+, +aclocal+, 
+automake+. The default program path can be overriden in the Autotools.programs hash. For
instance, to be sure that <tt>automake-1.9</tt> is used <bb>for all packages</bb>, you set

    Autotools.programs['automake'] = 'automake-1.9'

Autobuild tries to detect what tools it should run, but you can override. Autodetection works
as follows:
* if a script named +autogen+ or +autogen.sh+ exists in the package source directory, it is run
  and the other tools are not. The name of this kind of script can be set by calling Autotools#use
    pkg.use :autogen => 'my_autogen_script'
* +autoheader+ is never used by default
* +autoconf+ is used if there is <tt>configure.ac</tt> or <tt>configure.in</tt> in the source dir
* +aclocal+ is used if +autoconf+ is enabled (either explicitely or by autodetection)
* +automake+ is used if there is a <tt>Makefile.am</tt> file in the source dir
* you can force to enable or disable any of these steps by calling Autotools#use. Set it to +true+
  to force its usage, +false+ to disable it or to a string to force the usage of a particular program
    pkg.use :autogen => false
    pkg.use :automake => false
    pkg.use :autoheader => true
    pkg.use :autoconf => 'my_autoconf_program'

  The 'autogen' option cannot be set to +true+.

The only program used during the build and install phases is +make+. Its path can be overriden 
in the Autobuild.programs hash
    Autobuild.programs['make'] = 'gnumake'

=== CMake

A cmake package is defined with
 
  require 'autobuild/packages/cmake'
  Autobuild.cmake :package_name do |pkg|
    <package configuration> ...
  end

The only configuration attribute available for CMake package is:
+builddir+ 
  the directory in which to configure and build the package. It is relative to
  the package sources. A global value can be defined through Autobuild::CMake.builddir

Additionally, the #define(name, value) method allows to define configuration variables.

== Available importers
You must set an importer object for each package. The package importer is the +importer+ attribute
and is set via <tt>package.importer = my_importer</tt>. An importer +foo+ is defined by the class
Autobuild::FooImporter and defines a Autobuild.foo method which creates a new importer object.
Importer classes files are in <tt>lib/autobuild/import/</tt>

=== Tar
    package.importer = tar(uri[, options])
    
Downloads a tarfile at +uri+ and saves it into a local cache directory.
The cache directory can be set in the +options+ hash
    package.importer = tar(uri, :cachedir = '/tmp')

It is "#{Autobuild.prefix}/cache" by default. The known URI schemes are file://
for local files and http:// or ftp:// for remote files.  There is currently no
way to set passive mode on FTP, since the standard open-uri library does not
allow that.

=== CVS 
    package.importer = cvs(cvsroot, module[, options])

Where +options+ is an option hash. See also Autobuild::CVSImporter and Autobuild.cvs

* the default CVS command is +cvs+. It can be changed by
    Autobuild.programs['cvs'] = 'my_cvs_command'
* the default checkout option is <tt>-P</tt>. You can change that by giving a +cvsco+ option
    cvs cvsroot, module, :cvsco => ['--my', '--cvs', '--options']
* the default update option is <tt>-dP</tt>. You can change that by giving a +cvsup+ option
    cvs cvsroot, module, :cvsup => ['--my', '--cvs', '--options']

=== Subversion
    package.importer = svn(url[, options])

Where +options+ is an option hash. See also Autobuild::SVNImporter and Autobuild.svn

* the default Subversion command is +svn+. It can be changed by
    Autobuild.programs['svn'] = 'my_svn_command'
* by default, no options are given to checkout. You add some by giving a +svnco+ option
    svn url, :svnco => ['--my', '--svn', '--options']
* by default, no options are given to update. You can add some by giving a +svnup+ option
    svn url, :svnup => ['--my', '--svn', '--options']

=== Darcs
    package.importer = darcs(url[, options])

Where +options+ is a hash. See also Autobuild::DarcsImporter and Autobuild.darcs

* the default Darcs command is +darcs+. It can be changed by
    Autobuild.programs['darcs'] = 'my_svn_command'
* by default, no options are given to get. You add some by giving a +get+ option
    darcs url, :get => ['--my', '--darcs', '--options']
* by default, no options are given to pull. You can add some by giving a +pull+ option
    darcs url, :pull => ['--my', '--darcs', '--options']

=== Git
    package.importer = git(url[, branch])

Imports the given branch (or master if none is given) of the repository at the
given URL. The branch is imported as the 'autobuild' remote and fetched into
the master local branch.

= Copyright and license
Author::    Sylvain Joyeux <[email protected]>
Copyright:: Copyright (c) 2005-2008 Sylvain Joyeux
License::   GPL