Development Environment

The Personal Robotics Lab uses the ROS software stack, meaning we do most development in C++ and Python on Ubuntu. Here we will present how to set up 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.

Creating a Catkin Workspace

All ROS development occurs inside a Catkin workspace. We use a command line tool called catkin to create, manage, and build Catkin workspaces.

To create a new Catkin workspace in the directory my-workspace, run:

$ mkdir my-workspace && cd my-workspace
$ wstool init src
$ catkin init
$ catkin config --extend /opt/ros/melodic

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 CMAKE_BUILD_TYPE to RelWithDebInfo or Release to enable compiler optimizations:

$ catkin config -a --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo

Checking Out Code

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 the following commands from your workspace:

$ cd src
$ wstool merge https://raw.githubusercontent.com/personalrobotics/pr-rosinstalls/master/herb-minimal-sim.rosinstall
$ wstool up

Installing Dependencies

$ 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=melodic --from-paths src

Building

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 setup.bash file. From your workspace, you can run this command:

$ . devel/setup.bash

Running 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

Rules of Thumb

• When creating a workspace:
  • Always explicitly extend another workspace using: catkin config --extend
• When adding a new package to a workspace:
  1. Checkout the source code in the src directory
  2. Build it using catkin build my_package
  3. Verify that the build succeeded
  4. Source setup.bash again
• When removing a package from a workspace:
  • Clean the workspace using catkin clean
• Miscellaneous:
  • If catkin prints a warning, then clean the workspace using catkin clean
  • Do not source any setup.bash files in .bashrc
  • Do not source more than one setup.bash file in a terminal window

Contributing Changes

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.

Creating a Tag/Release

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:

$ catkin_generate_changelog

If this is the first time you've released the package, then you need to pass the -a flag.

The previous command creates or updates a CHANGELOG.rst file in the current directory. Open this in your favorite text editor 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 major, minor, or 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.