---
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, layout of the
   installation. See "Management" below.
 * .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.

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.

Toplevel manifest
-----------------
The <tt>autoproj/manifest</tt> file is a yaml file which describes the package
sets that are available, and how packages are organized in the installation. It
looks like this:

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

The first section, the <tt>layout</tt> section, lists the packages or package
sets we want to have in this installation.  It is a layout, meaning that some packages
can be built and installed in a subdirectory of the main installation
(see "Layouts and dependencies" below). Packages are referred to by the name they
have in the autobuild file (see [this page for more details](source_yml.hml)).
Package sets are referred to by the name given in the [set's <tt>source.yml</tt>
file](source_yml.html), and are interpreted as "build all packages of the given
set".

The second section, the <tt>package_sets</tt> section, lists both local and remote
sets that are available to 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}

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}

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}

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

All the build-related commands given above (i.e. build, doc, and update) can be
given a package name or a name used as a subdirectory in the layout section of
the manifest.

In the first case, only the package and the dependencies _that are on the same
level on the installation layout_ are built. It means that 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_.