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