---
title: Writing autobuild scripts
sort_info: 200
---

Defining CMake packages
-----------------------
A simple cmake package is defined with

{coderay:: ruby}
cmake_package "package_name"
{coderay}

More complex tweaking is achieved with

{coderay:: ruby}
cmake_package "package_name" do |pkg|
  [modify the pkg object]
end
{coderay}

In particular, cmake build options can be given with

{coderay:: ruby}
cmake_package "package_name" do |pkg|
  pkg.define "VAR", "VALUE"
end
{coderay}

The above snippet being equivalent to calling <tt>cmake -DVAR=VALUE</tt>

The "pkg" variable in the example above is an instance of
[Autobuild::CMake](http://doudou.github.com/autobuild/Autobuild/CMake.html)
{: .block}

Defining autotools packages {#autotools}
---------------------------

{coderay:: ruby}
autotools_package "package_name"
autotools_package "package_name" do |pkg|
    pkg.configureflags << "--enable-feature" << "VAR=VALUE"
    # additional configuration
end
{coderay}

The 'pkg' variable in the example above is an instance of
[Autobuild::Autotools](http://doudou.github.com/autobuild/Autobuild/Autotools.html)
{: .block}

Defining Ruby packages
----------------------

{coderay:: ruby}
ruby_package "package_name"
ruby_package "package_name" do |pkg|
    # additional configuration
end
{coderay}

This package handles pure ruby libraries that do not need to be installed at
all. Autoproj assumes that the directory layout of the package follows the following
convention:

 * programs are in bin/
 * the library itself is in lib/

If a Rakefile is present in the root of the source package, its <tt>default</tt>
task will be called during the build, and its <tt>redocs</tt> task will be used
for documentation generation. The <tt>rake_setup_task</tt> and
<tt>rake_doc_task</tt> package properties can be used to override this default
setting:

{coderay::ruby}
ruby_package "package_name" do |pkg|
    pkg.rake_setup_task = "setup"
    pkg.rake_doc_task = "doc:all"
end
{coderay}

Additionally, they can be set to <tt>nil</tt> to disable either setup or documentation
generation. For instance, the following code disables documentation generation
and uses the +setup+ task at build time:

{coderay::ruby}
ruby_package "package_name" do |pkg|
    pkg.rake_setup_task = "setup"
    pkg.rake_doc_task = nil
end
{coderay}

The 'pkg' variable in the example above is an instance of
[Autobuild::ImporterPackage](http://doudou.github.com/autobuild/Autobuild/ImporterPackage.html),
with additional methods coming from [the RubyPackage
module](http://doudou.github.com/autoproj/api/Autoproj/RubyPackage.html)
{: .block}

Defining oroGen packages
------------------------

{coderay:: ruby}
orogen_package "package_name"
orogen_package "package_name" do |pkg|
    # customization code
end
{coderay}

oroGen is a module generator for the Orocos component framework. See [the oroGen
documentation](http://doudou.github.com/orogen) for more information.

The 'pkg' variable in the example above is an instance of
[Autobuild::Orogen](http://doudou.github.com/autobuild/Autobuild/Orogen.html)
{: .block}

Custom package building
-----------------------

{coderay:: ruby}
import_package "package_name" do |pkg|
    pkg.post_install do
        # add commands to build and install the package
    end
end
{coderay}

Declaring documentation targets
-------------------------------
Both autotools and cmake packages use <tt>make</tt> as the low-level build tool.
For both packages, you can declare a documentation target that will be used
during the call to <tt>autoproj doc</tt> to generate documentation:

{coderay:: ruby}
cmake_package "package_name" do |pkg|
  pkg.with_doc 'doc'
  pkg.doc_dir = "doc/html"
end
{coderay}

The <tt>doc_dir</tt> assignment above is needed if the package installs its documentation
elsewhere than "doc".

Defining dependencies
---------------------
Inter-package dependencies can be defined with

{coderay:: ruby}
pkg.depends_on "package_name"
{coderay}

Where package name is either the name of another autoproj-built package, or the
name of a package that is to be [provided by the operating system](osdeps.html).

Both methods should be used only for dynamic dependencies, i.e. dependencies
that are dependent on build options (see below). Static dependencies should be
defined in [the package's manifest.xml](manifest-xml.html)
{: .warning}

Finally, it is possible to give aliases to a package's name, by using the
Autobuild::Package#provides method. If one does

{coderay:: ruby}
cmake_package "mypkg" do |pkg|
    pkg.provides "pkgconfig/libmypkg"
end
{coderay}

then a package that declares a dependency on "pkgconfig/libmypkg" will actually
depend on "mypkg".

Defining and using options
--------------------------

It is possible to define configuration options which are set by your user at
build time. These options can then be used in the autobuild scripts to
parametrize the build.

The general form of an option declaration is:

{coderay:: ruby}
configuration_option "option_name", "option_type",
    :default => "default_value",
    :values => ["set", "of", "possible", "values"],
    :doc => "description of the option"
{coderay}

Once declared, it can be used in autobuild scripts with:

{coderay:: ruby}
user_config("option_name")
{coderay}

Options are saved in <tt>autoproj/config.yml</tt> after the build. Options that
are already set won't be asked again unless the <tt>--reconfigure</tt> option is
given to <tt>autoproj build</tt>.

Do not try to have too many options, that is in general bad policy as
non-advanced users won't be able to know what to answer. Advanced users will
always have the option to override your autobuild definitions to tweak the
builds to their needs.
{: .warning}