---
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.page) for the bootstrapping process.

Structure
---------

A autoproj installation is characterized by a autoproj/ directory in which all
autoproj-related configuration is saved. The contained files are as follows:

 * autoproj/manifest: list of available package sets, customization options.
   The first part is covered here, the second in the next page.
 * .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.

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 <tt>--no-update</tt> option to skip the update phase.
autoproj will still have to checkout new packages, though:

autoproj build --no-update
{.commandline}

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}