---
title: Customizing the installation
sort_info: 75
---

Changing the installation's layout
----------------------------------

The <tt>layout</tt> section of <tt>autoproj/manifest</tt> offers two things:
 * select which packages/package sets to build and
 * build packages in specific subdirectories

This section lists packages or package sets that ought to be built by autoproj.
For instance, in the following example, only the <tt>orocos/rtt</tt> and
<tt>orocos/ocl</tt>
packages of the rubim.orocos source will be built. The other will be excluded
from the build.

{coderay:: yaml}
package_sets:
  - type: git
    url: git://github.com/doudou/rubim.orocos.git

layout:
  - orocos/rtt
  - orocos/ocl
{coderay}

Instead of giving a package name, the name of a package set can be provided,
which translates into "all the packages of that set".

As we mentionned before, the layout mechanism also allows you to place packages
in subdirectories of the main installation. For instance, the following snippet
will build the <tt>typelib</tt>, <tt>utilmm</tt> and <tt>utilrb</tt> libraries of rubim.orocos into
the <tt>lib/</tt> subdirectory and all the <tt>orocos/</tt> packages in the root.

{coderay:: yaml}
layout:
  - lib:
    - typelib
    - utilmm
    - utilrb
  - orocos/
{coderay}

Configuration files like <tt>autoproj/manifest</tt> are YAML file. As such, they
aresensible to indentation. The snippet above should be read as: in the layout, there is first a "lib" part and second the packages whose names start with "orocos/" _(first level of indentation)_. In the "lib" part, the packages are "typelib", "utilmm"
 and "utilrb" _(second level of indentation)_. 
{.warning}

Alternatively, the example above could be written:
{coderay:: yaml}
layout:
  - lib: [typelib, utilmm, utilrb]
  - orocos/
{coderay}

Finally, names of sublayouts can be used as arguments in the autoproj command
line, instead of package names:

autoproj build lib
{.commandline}

Removing packages from the build
--------------------------------
Instead of having to list all packages that you do want to build, it is possible
to list the packages that you don't want to build. Simply list them in the
<tt>exclude_packages</tt> section of the manifest file. In the following example, all
of the rubim.orocos package set will be built *but* the pocosim-log package.

{coderay:: yaml}
layout:
  - rubim.orocos

exclude_packages:
  - pocosim-log
{coderay}

Using packages that are already installed
-----------------------------------------

If some packages are already installed elsewhere, and you want to use that
version instead of the one listed in the package sets, list them in the
<tt>ignore_packages</tt> section of the manifest. In the following example, the
<tt>orocos/rtt</tt> package will *not* be built by autoproj.

{coderay:: yaml}
layout:
  - rubim.orocos

exclude_packages:
  - pocosim-log

ignore_packages:
  - orocos/rtt
{coderay}

This differs from the <tt>exclude_packages</tt> mechanism: packages listed in
<tt>ignore_packages</tt> are assumed to be present even though autoproj does not manage
them, while packages in <tt>exclude_packages</tt> are assumed to be absent and therefore
issue an error if another package in the installation depend on them.

Local overrides of version control information
----------------------------------------------

The <tt>autoproj/overrides.yml</tt> allows you to override version control information
for specific packages. It has the same format than the source.yml file of
package sets, so [check that page out](source_yml.html) for more information.

This file can in particular be used to avoid further updates to a given software
package. Simply do:

{coderay:: yaml}
version_control:
  - orocos/rtt:
    type: none
{coderay}

Building local packages
-----------------------

You can list local packages that are not in an imported package set by placing
the definitions in autoproj/, in a file ending with <tt>.autobuild</tt>. See [this
page](source_yml.html) for information on how to write autobuild files.

Setting up the path to specific commands (make, parallel builds)
----------------------------------------------------------------

The autobuild API allows to specify what specific installed command to use for
each tool needed during the build. These commands can be used in
<tt>autoproj/init.rb</tt> to tune the build system. Example:

{coderay:: ruby}
Autobuild.commands['make'] = '/path/to/ccmake'
Autobuild.parallel_build_level = 10 # build with -j10
{coderay}

More complex customization
--------------------------

More complex customization can be achieved by accessing the Autoproj and
Autobuild API directly in the <tt>autoproj/init.rb</tt> and
<tt>autoproj/overrides.rb</tt>
files. The former is loaded before all source files and the latter is loaded
after all source files.

Some examples:

 * fixing dependencies: if a dependency is not listed in a package's manifest,
   then you can fix it by adding the following in <tt>autoproj/overrides.rb</tt>
   {coderay:: ruby}
   a = Autobuild::Package['a_package']
   a.depends_on "other_package"
   {coderay}

 * changing the configuration of some cmake package:
   {coderay:: ruby}
   a = Autobuild::Package['a_package']
   a.define "CONFIG_VAR", "CONFIG_VALUE"
   {coderay}

Building packages selectively on the command line
-------------------------------------------------

The autoproj command line accepts subdirectories defined in the layout as well
as package names.

For instance, with the following layout:

{coderay:: yaml}
layout:
  - typelib
  - asguard:
    - modules/base
    - modules/logger
{coderay}

If the command line is

autoproj build modules/logger
{.cmdline}

then only modules/logger and modules/base will be built -- assuming
modules/logger depends on modules/base -- but typelib will be left alone
_regardless of its state_. It may speed up the build process tremendously, but
also may generate errors if other packages needed to be updated.

Idem, if the command line is:

autoproj build asguard
{.cmdline}

then all packages or asguard/ are built _but none of the dependencies that are
defined in other places in the layout_.