The Personal Robotics Lab uses the ROS software stack, meaning we do most development in C++ and Python on Ubuntu 14.04. Here we will present how to setup the PRL development environment, how to create and manage packages, and the tools we use to do so. These instructions assume that you already followed the machine setup instructions to configure your development machine.
These instructions use the
catkin build command, which is part of the
catkin_tools package (
$ sudo apt-get install python-catkin-tools ). If you are using the older
catkin_make command, then you should consult the official Catkin documentation for the equivalent commands.
To create a new Catkin workspace in the directory
$ mkdir my-workspace && cd my-workspace $ wstool init src $ catkin init $ catkin config --extend /opt/ros/indigo
If you want to "overlay" a user made ROS workspace (e.g.
herb2_ws on herb2), add
/devel to the end of the workspace name, e.g.:
$ catkin config --extend /path/to/other_workspace/devel
Typically, you should also set
Release to enable compiler optimizations:
$ catkin config -a --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo
We use the
wstool to manage multiple version control repositories in a workspace. We maintain a set of files to easily download sets of packages required for various projects. See pr-rosinstalls for instructions and files.
For example, to install the code necessary to run HERB in simulation, run:
$ cd src $ wstool merge https://raw.githubusercontent.com/personalrobotics/pr-rosinstalls/master/herb-minimal-sim.rosinstall $ wstool up
manifest.xml files, leftover from the deprecated
rosbuild build system, can interfere with the operation of
rosdep. You can delete all
manifest.xml files by using this command in your workspace:
$ find src -name manifest.xml -delete
Many of our Catkin packages have third-party dependencies. Once you have initialized
rosdep, you can use it to install third-party dependencies:
$ rosdep update $ rosdep install -y -r --ignore-src --rosdistro=indigo --from-paths src
Once the checkout is complete, you can build the workspace by running:
$ catkin build
Once the build is complete, any build artifacts should be placed in the
devel directory. Before running these, you should source the
$ . devel/setup.bash
This section includes the bare minimum set of commands for running unit tests. See the unit testing guide for more information about unit tests.
Optionally, after building the workspace, you can run the included unit tests. This can catch missing dependencies, version incompatibilities, and other difficult-to-diagnose bugs. It is generally a good idea to run tests when you first checkout the workspace or add a package to it.
To execute the tests, run:
$ catkin build --make-args tests # build the tests $ catkin build --make-args test # run the tests
This may take several minutes to finish. Once the tests are complete, you can view the results by running:
$ catkin_test_results build/ Summary: 12 tests, 0 errors, 0 failures
catkin config --extend
catkin build my_package
catkin clean -a
catkinprints a warning, then clean the workspace using
catkin clean -a
setup.bashfile in a terminal window
All lab source code, public or private, is stored on our GitHub organization. We use the "fork and pull request" method for maintaining core repositories. Lab members have write access the to repositories, but all development must be done on feature branches and a pull request made to the master branch. Anyone else who wants to commit code to the project must fork the repository into their own GitHub account, commit code there, and then create a pull request back to the main (personalrobotics) repository. The owner/maintainer(s) are responsible for merging the pull requests and ensuring code quality.
Package owners should tag packages when they reach a stable version. The following commands can be used to create a new tag of a catkin package from the top-level directory of the package:
If this is the first time you've released the package, then you need to pass the
The previous command creates or updates a
CHANGELOG.rst file in the current directory. Open this in your favorite text message and clean it up by removing and merging unhelpful commit messages. Once you are done:
$ git add CHANGELOG.rst $ git commit $ catkin_prepare_release --bump=minor
You can pass
patch to the
--bump option. See this page on semantic versioning to help you decide which option is best for you:
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
This will generate a new tag in the git repository, and update the version number in the
package.xml file. This new tag can be used in a
.rosinstall via the version flag to link to the stable release of the code. See the
rosinstall.txt files in the
table_clearing releases for an example.