---
title: Managing autoproj installations
sort_info: 50
---

This page describes the structure of a autoproj installation, and describes how
to manage one. See [the introduction](index.html) for the bootstrapping process.

Structure
---------

!overview.png!
<img class="full" src="overview.png" />

The autoproj configuration and build process goes like this:

 * a set of packages are declared in _package sets_. These package sets can
   either be local (saved along with the rest of the autoproj configuration) or
   remote (imported from a VCS). They declare how to get, build and install
   a certain number of packages. On the image above, there are three of those
   sets: rubim.base, rubim.orocos and rubim.drivers.
 * packages that are relevant to the local installation are cherry-picked from
   the package sets. One can either select packages one-by-one (the case for the
   two packages of rubim.drivers above), or a package set can be imported as a
   whole (rubim.orocos and rubim.base).
 * autoproj will then import the selected packages, auto-select their
   dependencies and import them as well, build and install all of this.
 * the selected packages can be imported and built in subdirectories of the
   installation tree. In the above example, all packages from rubim.orocos are
   built in the tools/ subdirectory, one package of rubim.drivers in the
   perception/ subdirectory and so on.

In practice, the autoproj configuration is saved in an autoproj/ directory. It
is split like this:

 * autoproj/manifest: list of available package sets, package selection and
   installation layout (where to put what).
 * .remotes/\*: package sets that are imported from a remote version
   control system
 * autoproj/\*/: local sets, i.e. sets that have not been imported from a remote
   version control system.
 * autoproj\/init.rb, autoproj\/overrides.rb and autoproj\/overrides.yml:
   installation customization

The build is done in two steps:

 * each package is being built in a <tt>build</tt> subdirectory of the package's
   source (<tt>package_directory/build/</tt>)
 * it is then installed in the build/ directory at the toplevel of the autoproj
   installation

Moreover, the <tt>build/log</tt> directory contains the output of all commands
that have been run during the build.

Finally, a <tt>env.sh</tt> script is generated to set up your shell for the use
of the installed software.

Listing and adding package sets
-------------------------------
Package sets are listed in the <tt>package_sets</tt> section of
<tt>autoproj/manifest</tt> file. This section looks like this:

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

It lists both local and remote sets that are available for this installation.
Local sets are subdirectories of the <tt>autoproj/</tt> directory: for instance,
in the above example, autoproj will look at the <tt>autoproj/imoby/</tt>
directory. Remote sets are taken from remote version control systems. Its
general format is:

{coderay:: yaml}
  - type: version_control_type # git, svn, cvs, darcs
    url: repository_url
{coderay}

For the git importer, one of 'branch' or 'tag' options can be provided as well:
{coderay:: yaml}
  - type: version_control_type # git, svn, cvs, darcs
    url: repository_url
    branch: branch_to_track
    tag: tag_to_stick_to # it is branch OR tag
{coderay}

Imported package sets are saved in the <tt>.remotes</tt> directory of the
autoproj installation. The importers that are available for configuration are
the same than the ones available for the packages themselves, so see [this
page](package_sets/importers.html#all_importers) for the list of available importers.

Management
----------

To update and build a autoproj installation, simply do:

autoproj build
{.commandline}

It will ask the value of newly defined configuration options, import (or update)
code hosted remotely, and build it. autoproj will *not* ask you again about the
configuration questions you already answered, so if you want to change them, do:

autoproj build --reconfigure
{.commandline}

Alternatively, you can edit the autoproj/config.yml file directly.

If you are in a disconnected environment (i.e. no access to remote
repositories), use the fast-build mode, to skip the package update and OS
packages installation phases (autoproj will still check out new packages,
though):

autoproj fast-build
{.commandline}

The package update can be disabled with --no-update and the OS dependencies
installation with --no-osdeps. In practice, "autoproj fast-build" is equivalent
to autoproj build --no-update --no-osdeps
{.block}

If, on the other hand, you only want to update the source code, do

autoproj update
{.commandline}

Finally, if you want to make sure that your build is fresh, then do

autoproj rebuild
{.commandline}

A less intrusive version of it only forces all tools to reconsider building. It
is mainly useful for CMake when the build environment changed -- cmake caches a
lot of values. To trigger this, do

autoproj force-build
{.commandline}

To add a new set, one edits the <tt>autoproj/manifest</tt> file and adds it
there. Then, simply starting the build will update everything and rebuild what
is needed.

Documentation is generated only when asked explicitely:

autoproj doc
{.commandline}

All these commands (i.e. build, doc, and update) accept a package name as
argument, thus triggering build only for this package and its dependencies. For
instance:

autoproj build orocos/rtt
{.commandline}