= Introduction
== What's autobuild ?
Autobuild is a builder for a set of software packages. It takes as input a yaml config file as input and

* imports the package from a SCM or (optionnaly) updates it
* configures it (for instance for autoconf-based packages)
* builds and installs it

It takes the dependencies between packages into account in its build process.

== Example config explained

1.  This section is not used at all by autobuild. It is only here to define references 
    used in the reste of the config file

        variables:
          - &openrobots ':ext:sjoyeux@cvs.laas.fr/cvs/openrobots'
          - &openprs_cvs ':ext:sjoyeux@cvs.laas.fr:/usr/local/openprs/CVS-Repository'
          - &compilers [ "CC=gcc-3.3", "CXX=g++-3.3" ]
          - &global_prefix /home/doudou/laas/openrobots

2.  <tt>autobuild-config</tt> holds the configuration of the build tool itself. See the
    <b>Autobuild configuration</b> section for the available configuration options.

        autobuild-config:
          srcdir: &srcdir /home/doudou/laas/openrobots/tools
          prefix: &prefix /home/doudou/laas/openrobots/build/tools
          clean-log: true
        
          mail:
            to: sjoyeux@laas.fr
        
          environment:
            PATH: [ "/bin", "/usr/bin" ]
            LD_LIBRARY_PATH:
            PKG_CONFIG_PATH:

3.  +programs+ defines the tools autobuild should use instead of the its default values.
    See each the rest of the documentation to know what values are used.

        programs:
           aclocal: "aclocal-1.9"
           automake: "automake-1.9"

 
4.  the +packages+ sections is where packages are defined

        packages:

5.  options in <tt>common-config</tt> are merged in each package configuration. See 
    <b>Configuring packages</b> for the detailed merging rules.

            common-config:
                configureflags: *compilers
                prefix: ""

6.  Tell autobuild to build the pocolibs package. Two common options here: 
    *type*::    the builder to use. Available package types are currently +autotools+,
                +import+ and +genom+ (a tool used at my lab;)). See the <b>Available
                package types</b> section for their configuration.
    *import*::  the importer to use. Source definition for the importer is always in 
                the +source+ option.
    
            pocolibs:
                type: autotools
                import: cvs
                source: [ *openrobots, pocolibs ]

   
7. Autobuild takes the dependencies between packages into account. Just list in +depends+ 
   the packages which should be installed before this one is built.

            genom:
                type: autotools
                import: cvs
                source: [ *openrobots, genom ]
                depends: pocolibs





= Configuration file

The config file is {a Yaml file}[http://yaml4r.sourceforge.net/cookbook]. It is a hash where 
each element is a section:

  section1:
    option1: value
    option2: value
  section2:

In the documentation, I'll sometime use paths to reference the config options. For instance, 
+option1+ is <tt>section1/option1</tt>. The +to+ option in the configuration example
is <tt>autobuild-config/mail/to</tt>
  
Autobuild uses three sections:

<b>autobuild-config</b>::   main autobuild configuration. See <b>Autobuild configuration</b> below
*programs*::                the programs used by importers and builders. See each tool 
                            documentation for the list of used options
*packages*::                the list of packages to build. See <b>Package configuration</b> below
*defines*::                 this is used for variable interpolation. Any key/value pair defined in
                            this section can be used later in other parts of the config files using
                            the $key or ${key} notation

== Autobuild configuration (<tt>autobuild-config</tt>)
=== Misc options
*update*::    if false, do not update the packages that are already imported (default: true). You
              can also use the <tt>--no-update</tt> on the command line

=== Directories (<tt>autobuild-config/srcdir</tt>, <tt>autobuild-config/prefix</tt> and <tt>autobuild-config/logdir</tt>)
*srcdir*::    the path where programs are to be imported. See <b>Packages configuration</b> for 
              more information on how this option is used.
*prefix*::    the path where programs are to be installed. See <b>Packages configuration</b> for more 
              information on how this option is used.
*logdir*::    by default, autobuild does not displays the output of each subcommand it launches. 
              Insteads, it saves this output in log files. These log files are saved in +logdir+. 
              The default value is <tt>prefix/autobuild</tt>
<b>clean-log</b>:: if we must remove all logfiles before each autobuild run or if we should append to them. The
                   default is +true+, that is log files are removed. Note that if mailing is active, all log 
                   files are attached to notification mail.


=== Environment (<tt>autobuild-config/environment</tt>)
The <tt>autobuild-config/environment</tt> section lists the initial values for 
the environment variables. While packages builders shall update the environment 
variables as needed, you can have to set up a proper initial environment. Arrays 
are converted into strings by joining elements by ':'

For instance
    autobuild-config:
          environment:
            PATH: [ "/bin", "/usr/bin" ]
            LD_LIBRARY_PATH:
            PKG_CONFIG_PATH:

sets

    PATH="/bin:/usr/bin"
    LD_LIBRARY_PATH=""
    PKG_CONFIG_PATH=""


=== Mail (<tt>autobuild-config/mail</tt>)
If you want to receive a mail when the build has finished (on success and failures), set
at least the +to+ option, like this:

    autobuild-config:
        mail:
            from: autobuild@mymachine.rubyrules.org
            to: myself+autobuild@rubyrules.org
            smtp: localhost

Other options are:
*from*:: what to set in the <tt>From:</tt> field, default is <tt>autobuild@hostname</tt>
*smtp*:: the stmp server to use. Default is +localhost+

All log files relative to the current build are attached to the mail.



== Configuring packages (<tt>packages/*</tt>)
=== The <tt>packages/common-config</tt> section
If you want to add common options in each package, just set it them here. Note that the options
are /merged/ in the package config. It neither replaces the values in the package nor be replaced
by them. The merging strategy depends on the way the <tt>common-config</tt> is specified:
* if it is an array, the package option is converted to an array and the common option is appended
* if it is a string, the package option is converted to a string and the common option is appended
with a space inserted between the two
* if it is a boolean value, it is <em>overriden</em> by the package value
* any other values are forbidden

To ease the config file writing, all options that accept arrays also accept a string when there 
is only one element. <b>Do not</b> do that in the <tt>common-config</tt> option.

=== Package definition
All subsections of the <tt>packages/</tt> section but <tt>common-config</tt> are package definitions
The section name is used as the package name. The package definition sets up the importer to get the
source and the builder to build and install it.

*type*::    the package type. See the <b>Available package types</b> sections

*srcdir*::  where sources are to be imported. If this is a relative path, it is relative to the global
            <tt>/autobuild-config/srcdir</tt> option. Otherwise, the absolute path is used. If no +srcdir+
            is given, the package name is used, so that the default import dir is 
            <em>global srcdir</em>/<em>package_name</em>.
        
            *Note* because of most SCM operations, it is forbidden that two packages have the same srcdir.
            Empty srcdir are forbidden for the same reason.

*importer*::    
            the importer type. For now, only +cvs+ and +svn+ are available. See the <b>Available importers</b>
            section.

<b>importer/source</b>:: 
            where the importer should get the sources. The format of this options depends on
            the importer used. See Available importers.

*prefix*::  where the program is to be installed. If this is a relative path, it is relative to the global
            <tt>/autobuild-config/prefix</tt> option. Otherwise, the absolute path is used. If no prefix
            is given, the package name is used, so that the default install dir is 
            <em>global prefix</em>/<em>package name</em>

*depends*::     the array of packages that should be built and installed before this one is built. <tt>depends: [ foo ]</tt>
                is equivalent to <tt>depends: foo</tt>. To make the use of +depends+ in the <tt>common-config</tt> 
                section possible, this package name is automatically removed from the package +depends+ array.
*provides*::    defines aliases for this package. As for +depends+, an array with only element can be replaced
                by the simple value.

== Available importers
=== CVS (<tt>type: cvs</tt>)
*source*::  the source specification is a [ repository, module ] array
*cvsup*::   options to add to cvs up. Defaults to '-dP'
*cvsco*::   options to add to cvs ci, Defaults to -P

=== Subversion (<tt>type: svn</tt>)
*source*::  the svn URL. To ease the Yaml nodes reference (the <tt>*ref</tt> form), it can be an array
            which is then converted into a path by joining the elements with '/'. For instance:
    
                packages:
                    foo:
                        import: svn
                        source: [ *my_home_repository, /trunk/foo ]

*svnup*::   options to add to svn up. Defaults to ''
*svnco*::   options to add to svn co. Defaults to ''

== Available package types (<tt>packages/</tt><em>name</em><tt>/type</tt>)
=== Source only (<tt>type: import</tt>)
Use +import+ if you need the package sources but don't need to build it. You just need
to set up the importer and +srcdir+. +prefix+ is ignored.

    packages:
        bar:
            type: import
            import: cvs
            source: [ *my_repository, "bar" ]
            srcdir: bar

=== Autotools (<tt>type: autotools</tt>)
Use this to build GNU autotools-based packages. This handles autoconf-only packages as 
well as automake-based packages.

==== Configuration programs
The <tt>autotools</tt> packages use four programs: *autoheader*, *autoconf*, *aclocal*, 
*automake*. The default values can be overriden in the <tt>/programs</tt> section. For 
instance, to be sure that automake 1.9 is used, you set

    programs:
        automake: automake-1.9

Autobuild tries to detect what tools it should run
* +autoheader+ is never used by default
* +autoconf+ is used if there is <tt>configure.ac</tt> or <tt>configure.in</tt> in the imported 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 imported dir
* you can force to enable or disable any of these four tools in each package config by setting the tool
  flag to true or false. For instance, if you don't want package +foo+ to use automake, you say

    packages:
        foo:
            automake: false

==== Build programs
The only program used during the build phase is +make+. The make command can too be overriden in the
<tt>programs</tt> section.

    programs:
        make: gnumake

==== Other options
*builddir*::    the directory where the build takes place. For now, it has to be a relative path, 
                which is added to the import dir. The default value is "build"
*configureflags*::  array of options to add to the +configure+ command line
                        configureflags: [ --with-bar-source=$srcdir/$bar_srcdir ]
                        depends: bar

= Running autobuild in daemon mode
The <tt>--daemon</tt> command line options makes autobuild go into daemon mode.
 
= Copyright and license
Author::    Sylvain Joyeux <sylvain.joyeux@m4x.org>
Copyright:: Copyright (c) 2005 Sylvain Joyeux
License::   GPL