---
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 an extension needs to be built, a Rakefile has to be there with a "setup"
   target to do the job.

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}

In the same way, if the source package depends on an OS package (see
[Prepackaged dependencies](os_deps.html) for details), you can use

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

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}