Day-to-day workspace commands

This page covers the autoproj commands and behavior that make most of the days within a Rock workspace. More advanced topics are covered later in the documentation.

CLI help

At any point, the autoproj CLI is documented through the –help option.

autoproj --help

Folder Structure

Workspace root
Where your ran the bootstrap, and where the env.sh script is located
The autoproj/ folder
Located at the root of the workspace, it contains all the build configuration
Remotes
The package build configuration downloaded by Autoproj, they are made available in autoproj/remotes/
Package
Packages are the unit that autoproj deals with. The Rock software is split into separate types of packages that are defined in the build configuration. The configuration tells Autoproj both the package type (how to install the package) and where the package's source code is located (e.g. the github repository).
OS Depedency or osdep
Packages in autoproj can either be checked out and built from source. Alternatively, autoproj allows to interact with the host OS package system (e.g. APT on Ubuntu). The osdep system is what makes this possible.
Build folders
When packages have build byproducts, they are saved within the package build folder. This is by default the build/ directory under the packages.
Prefix folder
Packages that require an install step will install under this folder. By default the install/ folder under the workspace root
Logs
The output of all commands ran by autoproj are redirected to separate files under install/log/

Moving around

acd allows to move from package to package within the workspace. Because it is a very common operation, acd accepts that each part of the package name be shortened as long as the result is unambiguous.

For instance, in the default Rock installation:

$ acd d/g
# Now in drivers/gps_base
$ acd c/k
multiple packages match 'c/k' in the current autoproj installation: control/kdl, control/kdl_parser
$ acd c/kdl
# Now in control/kdl
$ acd c/kdl_par
# Now in control/kdl_parser

acd expects package names or package directories. A few packages – mainly orogen, typelib and rtt – do not include the package's category in them (they are named e.g. 'orogen' but are installed in tools/). autoproj show path/to/directory will allow you to find this out.

The -b and -p options allow to move to a package's build and prefix directories.

$ acd -b d/gps
# Now in drivers/gps_base/build
$ acd -p c/kdl
# Now in install/

Logs

During build, and less often during updates, the tools autoproj calls will error out. However, to keep the output of autoproj manageable, it redirects the command output - where the error details usually are - to separate files.

When one error does happen, autoproj displays the last 10 lines of that command. The intent is that these 10 lines may contain the error. If it does not, the easiest way to display the output of the failed command is to run alog with either the name of the failed package or its path

alog name/of/package
alog path/to/package

Or, if your shell is already within a folder of said package,

alog .

Note that the logs are ordered by last modified date (the most recently modified being first). The first entry is therefore most likely the one you're looking for after an update or build failure.

Updating

Most of the time, you will want to update the whole workspace (the -k option continues updating even if errors occur). This will also update OS dependencies.

aup --all -k

If you want to restrict the update to a package and its dependencies, give its name or path on the command line

aup simulation/rock_gazebo

If given the path to a directory (as opposed to an actual package), it will update all packages under this directory

# Update all drivers libraries and orogen packages
aup drivers/

Without arguments, it will update the package within the current directory

aup
# Which is basically equivalent to
aup .

If you want to update a package but not its dependencies, use -n, e.g.

aup -n
aup -n simulation/rock_gazebo
cd simulation
aup -n rock_gazebo

Finally, if you want to checkout missing packages, but without updating already checked out packages, use --checkout-only. This is useful if you want to install new packages, but not modify the already-installed ones.

# Checkout all missing packages in the dependency chain of drivers/orogen/iodrivers_base
aup --checkout-only drivers/orogen/iodrivers_base

All aup commands that concern specific package(s) will not update the workspace configuration. To update everything including the configuration, either run aup from within the workspace root, or aup --all from any directory. If you want to only update the configuration, do aup --config

In some situations, or if you're trying to keep track of all the changes that are happening to your system, you want want to check what will be pulled by aup. autoproj status allows to compare the status of the workspace w.r.t. the repositories. In case the changes would modify the configuration, it's a good idea to first update the configuration and re-run autoproj status to include possible changes in the package source information:

aup --config
autoproj status

Building

To ensure that all changes have been built, run

amake --all

As with aup, -k can be added to continue even under error. This is less common for amake, though, as a build error will usually cascade to its dependencies.

If you want to restrict the build to a package and its dependencies, give its name or path on the command line

amake simulation/rock_gazebo

To restrict the build to the package, excluding its dependencies, add -n.

amake without arguments is equivalent to amake .: update the package located in the current directory. If called outside of a package, it means "update all packages under this directory". amake in the root of the workspace is therefore equivalent to amake --all.

Configuration

Build configurations may have some configuration options. These options are asked during the first build. If you need to change the answers after the first run, execute

autoproj reconfigure

Running Tests

Test suites are expensive to build, and one does not want every test suite from every package to be available at all time. For this reason, test suite building is by default disabled for all packages. If you do want to use/develop the test suite of a package (great idea !), you need first to enable it, update and rebuild. The 'update' step is needed as some dependencies are only installed for the purpose of testing.

From within the package's directory,

autoproj test enable .
aup --no-deps
amake

autoproj disable path/to/package does the reverse.

Use autoproj test list to see which packages do have a test suite and for which packages it is enabled.

Running the tests can either be done using the package's test method, or through autoproj by running

autoproj test .

If you do want to enable all unit tests for all packages, run enable without arguments. disable without arguments disables all test suites.

Next: let's get to create our first system integration