Create a catkin workspace and a ROS package
Requirements for this page:
ROS is installed on the computer you are working on (be that working “directly” on the computer or remotely connected to it).
A git account that you can push to and pull from on the computer with ROS installed.
Contents of this page
TL;DR
Of course you did already read everything below, and the following TL;DR summary is just for convenience when you return to remind yourself of a small detail:
# SOURCE THE ROS setup.bash FILE
source /opt/ros/melodic/setup.bash
# MAKE THE CATKIN WORKSPACE DIRECTORY
cd ~
mkdir my-robotics-system
cd my-robotics-system
mkdir catkin_ws
# INITIALISE THE CATKIN WORKSPACE
cd catkin_ws
mkdir src
catkin_make
# SOURCE THE devel/setup.bash FILE FROM THE CATKIN WORKSPACE
source devel/setup.bash
# CREATE THE ROS PACKAGE
cd src/
catkin_create_pkg my_robotics_pkg std_msgs rospy roscpp
# EDIT THE DETAILS IN THE PACKAGE XML FILE
nano my_robotics_pkg/package.xml
# ADD A GIT IGNORE FILE
cd ~/my-robotics-system
nano .gitignore
# COMMIT AND PUSH TO YOUR BLANK GIT REPOSITORY
cd ~/my-robotics-system
git init
git remote add origin
https://gitlab.unimelb.edu.au:foobar/my-robotics-system.git
git add .
git commit -m "Initial commit"
git push -u origin master
Suggested contents for a .gitignore file:
# Ignore the "build" and "devel" folder of the catkin_ws
catkin_ws/build/
catkin_ws/devel/
# Ignore the ".catkin_workspace" file of the catkin_ws
catkin_ws/.catkin_workspace
# Ignore the auto-generated "CMakeLists.txt" of the catkin_ws
catkin_ws/src/CMakeLists.txt
# Ignore swp files and other typically unwanted files
*.swp
.DS_Store
Source the ROS setup.bash
In order to have the various ROS commands available from command line, you need to source the setup.bash of your ROS installation. This file is located at the following location:
/opt/ros/<ros-distro>/setup.bash
where <ros-distro> is replaced by the name of the ROS distribution you are using. For example, if you are using ROS melodic, then the source command to enter in terminal is:
source /opt/ros/melodic/setup.bash
This step needs to be completed for each new terminal window or ssh connection that you open.
(Optional) add ROS setup.bash to the .bashrc
You can save yourself entering the source command every time by adding it to the .bashrc file. The .bashrc file is a bash script that runs every time you open a new terminal window or ssh connection. In general, there is a simple pro and con of adding command to the :
Pro: Saves you entering (or forgetting) to the command.
Con: Over time you forget what was added to the
.bashrcfile, and perhaps in the future a command there cause errors that you cannot explain.
Adding the ROS setup.bash to the .bashrc file is a pretty safe bet for a computer that you regularly use to run ROS.
The .bashrc file is located in the home directory of the logged in user. Hence:
Use
cd ~to change to the users home directory,Then
ls -lato list all files and see that the.bashrcfile indeed existsThen
nano .bashrcto edit the file (or use whichever editor you prefer, possiblyvi .bashrc)Add the following lines of code to the end of the
.bashrcfile (where the first line is a comment to remind you future-self what this command does):# SOURCE THE ROS setup.bash FILE source /opt/ros/melodic/setup.bash
What does the rc stand for anyway, you may ask. It is a relic from the 1960’s and stands for RUNCOM according to this Wikipedia page, where they provide the quote:
There was a facility that would execute a bunch of commands stored in a file; it was called runcom for “run commands”, and the file began to be called “a runcom”. rc in Unix is a fossil from that usage.
Make the catkin_ws directory
Key to how ROS works is a prescribed directory structure for where you place the various pieces of code you write. As an additional layer to that, the goal of this page it to start a git repository with your ROS code so that you can write code from any computer, push it up to the repository, and then pull it down to your ROS computer for testing (i.e., pull the code to your robot).
Create a directory for the git repository:
cd ~
mkdir my-robotics-system
where you can replace my-robotics-system with any directory name you wish.
Create a catkin_ws directory:
cd my-robotics-system
mkdir catkin_ws
where ws stands for work space and catkin is the official build system of ROS, hence this directory is the space where you do all of your ROS work.
Note
You can in fact use a directory name different from catkin_ws, but using catkin_ws is a good convention because then everyone knows to expect the sub-folder structure described on the rest of this page and on the ROS Wiki catkin workspaces page.
Use catkin_make to initialise
The catkin_make command is the main tool for working with catkin workspaces. We use it now to initialise our catkin workspace. But first we need to have a src directory:
cd catkin_ws
mkdir src
catkin_make
After catkin_make has finished, you can list the contents with ls -la to see what was created:
catkin_ws/
.catkin_workspace
build/
devel/
src/
CMakeLists.txt -> /opt/ros/melodic/share/catkin/
And you see that within the devel/ there is a setup.bash file.
Source the setup.bash of the catkin workspace
In order to have the content of the catkin workspace available to work with from command line, you need to source the setup.bash file from the devel folder created in the previous step, i.e.,
source devel/setup.bash
This step needs to be completed for each new terminal window or ssh connection that you open.
(Optional) add the catkin workspace setup.bash to the .bashrc
Similar to above, edit the .bashrc to add the following lines at the end:
# SOURCE THE devel/setup.bash FILE FROM THE CATKIN WORKSPACE
source ~/my-robotics-system/catkin_ws/devel/setup.bash
Note
It is less clear whether adding the catkin workspace devel/setup.bash to the .bashrc file always make sense. For example, if you have multiple copies of the same catkin_ws, each for testing a different feature (which may each be a separate branch of your git repository), then you only want to source the catkin_ws relevant for the tests you are about to perform. Hence have one of then in the bashrc (the one on the master branch for example) may cause more lost time in confusion that the time it saves in typing the source command every time.
Double check what is on the ROS_PACKAGE_PATH
If at any time you need to double check which setup.bash files are already source for the current terminal session, then you simply need to echo the ROS_PACKAGE_PATH environment variable:
echo $ROS_PACKAGE_PATH
The following is an example results of the echo:
/home/asc/my-robotics-system/catkin_ws/src:/opt/ros/melodic/share
indicating that the catkin workspace and ROS melodic setup.bash files are sourced.
What is a ROS Package
A ROS package is essentially a self-contained grouping of ROS code that serves a particular purpose. Self contained in the sense that everything needed to compile and run the ROS nodes contained in the package. The purpose of a package can range anywhere from being narrow and highly specialised to being broad and general. For example, you might create a package specifically for path planning, or you might create a package for generally doing every part of your robotics project.
The main benefit of compartmentalising functionality into packages is that you and others can easily add a package and its functionality to existing projects. To gain the benefits of adding a package, it should be well documented and provide sufficient abstraction of the implementation details.
As a general rule, start your robotics project with everything in one pacakge, and as things mature you can carve away certain functionalities into separate packages.
Create a ROS Package
A catkin workspace can have multiple packages, and the root of all packages must be in the catkin_ws/src/ directory. Hence change to that directory before using the create package command:
cd src/
The command catkin_create_pkg will create the skeleton of a ROS package, it uses the following syntax:
catkin_create_pkg <package_name> <dependencies>
where <package_name> is replaced by the name you wish to give you package, and <dependencies> is a list what standard ROS packages your package depends on. For example, create a package for your robotic system using the following:
catkin_create_pkg my_robotics_pkg std_msgs rospy roscpp
The dependencies std_msgs, rospy, and roscpp are the minimum you should include to be able to write ROS nodes in C++ or Python and communicate between the nodes with standard message types.
Note
You can change the dependencies of your package at a later time.
Interrogating and customizing your package
The create package command above create a folder with the name of your package, e.g., my_robotics_pkg, and within that folder it creates the following four items:
package.xmlthat provides all the high-level details of your package.
CMakeLists.txtthat provides the CMake instructions for how the contents of your package is to be compiled.
srcfolder, where you can add and develop the source code for your robotics project.
includefolder, where you can add the header files you create and develop.
You should now edit the package.xml file to include all the relevant details. A good guide for doing this is provided by the ROS Tutorial: Customizing the package.xml
The CMakeLists.txt is something we will return to multiple times when necessary. For now you can skim through the auto-generated comments in the CMakeLists.txt to get a feeling for what goes in there.
Git ignore and git push
Having completed the steps above, now is a good time to commit and push changes to your git repository.
Most of the files automatically generated by the steps above do not need to be committed to your git repository because they would be automatically generated again. Hence add a .gitignore file to the root of your git repository:
cd ~/my-robotics-system
nano .gitignore
and put the following as the contents of the .gitignore file:
# Ignore the "build" and "devel" folder of the catkin_ws
catkin_ws/build/
catkin_ws/devel/
# Ignore the ".catkin_workspace" file of the catkin_ws
catkin_ws/.catkin_workspace
# Ignore the auto-generated "CMakeLists.txt" of the catkin_ws
catkin_ws/src/CMakeLists.txt
# Ignore swp files and other typically unwanted files
*.swp
.DS_Store
Now you can commit and push the changes to my-robotics-system git repository. How exactly to do this depends on how or whether you have setup the existence of a my-robotics-system git repository on your chosen git hosting hosting platform.
Assuming you are using a gitlab instance and you have created a blank project named my-robotics-system, then use the following commands to commit and push:
cd ~/my-robotics-system
git init
git remote add origin
https://gitlab.unimelb.edu.au:foobar/my-robotics-system.git
git add .
git commit -m "Initial commit"
git push -u origin master
The
foobaron line 4 should be replaced by your username on thegitlab.unimelb.edugitlab instance, if that is indeed what you are using.The
https://on line 4 can be replaced bygit@if you prefer to use ssh authentication instead of password authentication.
References
The steps detailed on this page are mostly taken from:
