Changing the installation’s layout

The layout section of autoproj/manifest 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 orogen and tools/orocos.rb packages of the rock.core package set and their dependencies will be built. The other will be ignored.

package_sets:
 - github: rock-core/package_set

layout:
 - orogen
 - tools/orocos.rb

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 typelib, utilmm and utilrb libraries of orocos-toolchain into the lib/ subdirectory and all the orocos/ packages in the root.

layout:
 - lib:
   - typelib
   - utilmm
   - utilrb
 - orocos/

Configuration files like autoproj/manifest are YAML file. As such, they are sensible 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).

Alternatively, the example above could be written:

layout:
 - lib: [typelib, utilmm, utilrb]
 - orocos/

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

autoproj build lib

Removing packages from the build (exclude_packages)

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 exclude_packages section of the manifest file. In the following example, all of the rock-core package set will be built but the pocolog package.

package_sets:
 - github: rock-core/package_set
layout:
 - rock.core
exclude_packages:
 - tools/pocolog

If another required package (i.e. a package listed in the layout) depends on an excluded package, the default behaviour is to fail with an error.

For some package sets, such as the rock package set, this behaviour can be relaxed by setting the package set’s weak_dependencies flag to true in e.g. the package set’s init.rb or autoproj/init.rb:

ruby metapackage('rock').weak_dependencies = true

In this case, autoproj will only issue a warning and simply automatically exclude the offending packages from the build.

Using packages that are already installed (ignore_packages)

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 ignore_packages section of the manifest. In the following example, the rtt package will not be built by autoproj, but autoproj will assume that it is present.

package_sets:
 - github: rock-core/package_set
layout:
 - rock.core
exclude_packages:
 - tools/pocolog
ignore_packages:
 - rtt

Unlike with exclude_packages, no error is generated for ignored packages that are depended-upon by other packages in the build. This is because ignore_packages is meant to list packages that are already installed outside of autoproj, while exclude_packages lists what you do not want to have at all.

Local overrides of version control information

The autoproj/overrides.yml 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 for more information.

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

overrides:
 - rtt:
   type: none

To track a different branch that the default branch, you will have to do:

overrides:
 - rtt:
   branch: experimental

Tuning what files autoproj looks at to determine if a package should be updated

When a package A depends on a package B, autoproj checks if some of the files in B’s directory are newer than the latest build of A. If it is the case, it will trigger the build of B and then the one of A.

Autoproj has a default list of files that it should ignore. Unfortunately, it may be that you are generating some files in the source directory that autoproj interprets as new files and trigger builds.

If you have the impression that autoproj does too many rebuilds, run the build once with the --list-newest-files option. For instance,

autoproj --list-newest-files fast-build

If you find some files that should be ignored, add them either to the package sets (i.e. autoproj/remotes/blablab/init.rb) or in autoproj/init.rb with

ignore /a_regular_expression/

where /a_regular_expression/ is a regular expression matching your files. For instance, to eliminate all files that have an extension in “.swp”, one would do

ignore /\.swp$/

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 .autobuild. See this page 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 autoproj/init.rb to tune the build system. Example:

Autobuild.programs['make'] = '/path/to/ccmake'
Autobuild.parallel_build_level = 10 # build with -j10

More complex customization

More complex customization can be achieved by accessing the Autoproj API and the Autobuild API directly in the autoproj/init.rb and autoproj/overrides.rb 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 autoproj/overrides.rb

  a = Autobuild::Package['a_package']
  a.depends_on "other_package"
  

• changing the configuration of some cmake package:

  a = Autobuild::Package['a_package']
  a.define "CONFIG_VAR", "CONFIG_VALUE"
  

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:

layout:
 - typelib
 - asguard:
   - modules/base
   - modules/logger

If the command line is

autoproj build modules/logger

then modules/logger and its dependencies will be built. Idem, if the command line is:

autoproj build asguard

then all packages or asguard/ are built, including their dependencies