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 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
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),
/devel to the end of the workspace name, e.g.:
$ catkin config --extend /path/to/other_workspace/devel
Typically, you should
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
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
manifest.xml files, leftover from
rosbuild build system, can
interfere with the operation of
rosdep. You can delete all
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
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
directory. Before running these, you should source the
setup.bash file. From
your workspace, you can run this command:
$ . 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
catkinprints a warning, then clean the workspace using
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 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
patch to the
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
via the version flag to link to the stable release of the code. See the
rosinstall.txt files in
table_clearing releases for