the Robot Construction Kit
A package set is made of three things:
To create a new package set that is going to be shared with others, the simplest solution is to
push it to whatever VCS you want. For git and gitorious, you would do something like
git init git add source.yml git commit -m "create the my_package_set_name package set" git push firstname.lastname@example.org:my-project/package_set.git
add the package set to autoproj/manifest and run
At this stage, the empty set is properly checked out in autoproj/remotes/my_package_set_name. You can add package definition and VCS information (see below), test it with autoproj update an autoproj build, commit and push !
If you are not going to share the package set, the simplest solution is to just add the autobuild and version control information in autoproj/local.autobuild and autoproj/overrides.yml – i.e. to not create a separate package set at all.
Adding a package to a package set involves changing two files:
For the first step, you need to add one of the following lines:
cmake_package "my/package" # for CMake package autotools_package "my/package" # for autoconf/automake packages orogen_package "my/package" # for orogen packages import_package "my/package" # for custom packages ruby_package "my/package" # for ruby libraries (optionally with C/C++ extensions)
The package name will be used to refer to this particular package later on – especially for version control definition. If subdirectories are used, like “my” in the above example, the package source will be checked out and built in the corresponding subdirectory. For instance, with
the hokuyo driver will always be built in a drivers/ subdirectory.
Now that the package is declared, we need to add version control information to the source.yml file. This needs to be done in the version_control section of the file, as for instance:
version_control: - my/package: type: git url: git://gitorious.com/blabla/my-package.git
The corresponding subversion definition would be:
version_control: - my/package: type: svn url: svn+ssh://svnhosting.com/blabla/trunk/my/package
For testing purposes, it is possible to tell autoproj to not take into account any VCS information:
version_control: - my/package: none
See this page for details on the import mechanisms.
The autobuild scripts lists all the packages defined by this set. It is a Ruby script (but you don’t need to know Ruby to write one). In its most simple form, it looks like:
cmake_package "orocos/rtt" autotools_package "drivers/imu" orogen_package "modules/imu" import_package "external/sisl" ruby_package "orocos/orocos.rb"
The above snippet lists the kind of packages autoproj currently supports. The first one uses CMake as a build system and will be installed in the orocos/rtt subdirectory of the autoproj installation. The second one is an autotools package. Additionally, there is support for orogen packages (i.e. Orocos components generated with orogen), packages that should be just imported but not build, and for Ruby packages. Package definitions can be tweaked quite a lot, including the ability to generate documentation. See the next page for more information on how to write autobuild scripts.
The source.yml file gives generic information on the package set itself (most importantly its name), and version control information (i.e. where to get the packages). It is a YAML file, and looks like:
name: rock.drivers constants: ROOT_DIR: $HOME/share version_control: - "modules/.*": type: git url: $ROOT_DIR/$PACKAGE_BASENAME.git - "drivers/.*": type: svn url: svn+ssh://rlbsvn.informatik.uni-bremen.de/trunk/$PACKAGE.git
The name field gives a name for the set. It is arbitrary, but the guideline is to give a name that is java-like for namespaces, i.e. origin.name.
The constants: section lists values that can be reused for different packages. Autoproj defines muliple constants:
It is also possible to use configuration variables, that get asked to the user during the build (see below).
Finally, the version_control: section describes how to import each software package. Its general format is:
package_name: type: version_control_type # git, svn, cvs, darcs url: repository_url
Where package_name is a regular expression that matches the package name (for instance, “.*” will match all packages and “drivers/.*” will match packages whose name starts with ‘drivers’). The package name is the one given to the blabla_package stanza in the autobuild file.
For the git importer, one of ‘branch’ or ‘tag’ options can be provided as well:
package_name: branch: branch_to_track tag: tag_to_stick_to # it is branch OR tag
The options are applied in order, meaning that the top entries will be overridden by the lower ones. In general, one will have a “.*” entry to give options for all packages, and then override for specific packages:
version_control: - .*: # common options for all packages type: git url: $ROOT_DIR/$PACKAGE.git - "modules/logger": # we don't follow master on this module branch: imoby
When multiple package sets are used, it is possible to override the version control definitions in low-priority sets with a higher priority one. Autoproj has the following rules when searching for version control information:
autoproj offers a configuration system that allows the user to tweak the build to its needs. If the version control definitions depend on such configuration options (as, for instance, because you want to parametrize the importer URLs), then create an init.rb file next to the source.yml file, and add lines looking like:
configuration_option "option_name", "option_type", :default => "default_value", :values => ["set", "of", "possible", "values"], :doc => "description of the option"
where the option_type field can either be “string” or “boolean”.
Then, you can use the option_name as an expansion in the source.yml file.
For instance, at my lab we are using an share filesystem to store the git repositories. Our project’s init.rb file has the following option definition:
configuration_option "MOUNT_POINT", "string", :default => "$HOME/nfs", :doc => "mount point of the NFS server"
And the source.yml uses it with:
version_control: ".*": url: $MOUNT_POINT/git/$PACKAGE.git type: git