 Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags. |
Installing and Configuring Your ROS Environment
Description: This tutorial walks you through installing ROS and setting up the ROS environment on your computer.Tutorial Level: BEGINNER
Next Tutorial: Navigating the ROS Filesystem
Note: The ROS Wiki is generally for ROS 1 only! If you have installed ROS 2 please use the ROS 2 documentation website.
Install ROS
Before starting these tutorials please complete installation as described in the ROS installation instructions.
Note: If you installed ROS from a package manager like apt, then those packages will not be write accessible and should not be edited by you the user. When working with ROS packages from source or when creating a new ROS package, you should always work in a directory that you have access to, like your home folder.
Managing Your Environment
During the installation of ROS, you will see that you are prompted to source one of several setup.*sh files, or even add this 'sourcing' to your shell startup script. This is required because ROS relies on the notion of combining spaces using the shell environment. This makes developing against different versions of ROS or against different sets of packages easier.
If you are ever having problems finding or using your ROS packages make sure that you have your environment properly setup. A good way to check is to ensure that environment variables like ROS_ROOT and ROS_PACKAGE_PATH are set:
$ printenv | grep ROS
If they are not then you might need to 'source' some setup.*sh files.
Environment setup files are generated for you, but can come from different places:
- ROS packages installed with package managers provide setup.*sh files
rosbuild workspaces provide setup.*sh files using tools like rosws
Setup.*sh files are created as a by-product of building or installing catkin packages
Note: Throughout the tutorials you will see references to rosbuild and catkin. These are the two available methods for organizing and building your ROS code. rosbuild is not recommended or maintained anymore but kept for legacy. catkin is the recommended way to organise your code, it uses more standard CMake conventions and provides more flexibility especially for people wanting to integrate external code bases or who want to release their software. For a full break down visit catkin or rosbuild.
If you just installed ROS from apt on Ubuntu then you will have setup.*sh files in '/opt/ros/<distro>/', and you could source them like so:
$ source /opt/ros/<distro>/setup.bash
Using the short name of your ROS distribution instead of <distro>
If you installed ROS Kinetic, that would be:
$ source /opt/ros/kinetic/setup.bash
You will need to run this command on every new shell you open to have access to the ROS commands, unless you add this line to your .bashrc. This process allows you to install several ROS distributions (e.g. indigo and kinetic) on the same computer and switch between them.
On other platforms you will find these setup.*sh files wherever you installed ROS.
Create a ROS Workspace
These instructions are for ROS Groovy and later. For ROS Fuerte and earlier, select rosbuild.
Let's create and build a catkin workspace:
$ mkdir -p ~/catkin_ws/src $ cd ~/catkin_ws/ $ catkin_make
The catkin_make command is a convenience tool for working with catkin workspaces. Running it the first time in your workspace, it will create a CMakeLists.txt link in your 'src' folder.
Python 3 users in ROS Melodic and earlier: note, if you are building ROS from source to achieve Python 3 compatibility, and have setup your system appropriately (ie: have the Python 3 versions of all the required ROS Python packages installed, such as catkin) the first catkin_make command in a clean catkin workspace must be:
$ catkin_make -DPYTHON_EXECUTABLE=/usr/bin/python3
This will configure catkin_make with Python 3. You may then proceed to use just catkin_make for subsequent builds.
Additionally, if you look in your current directory you should now have a 'build' and 'devel' folder. Inside the 'devel' folder you can see that there are now several setup.*sh files. Sourcing any of these files will overlay this workspace on top of your environment. To understand more about this see the general catkin documentation: catkin. Before continuing source your new setup.*sh file:
$ source devel/setup.bash
To make sure your workspace is properly overlayed by the setup script, make sure ROS_PACKAGE_PATH environment variable includes the directory you're in.
$ echo $ROS_PACKAGE_PATH /home/youruser/catkin_ws/src:/opt/ros/kinetic/share
When working with ROS source code, it is often useful to do so in a "workspace". For the following ROS tutorials you will need an area for working on tutorials and creating new ROS stacks and packages.
rosws is a tool that provides a uniform interface to various version control systems such as SVN, Git and Mercurial and for managing all packages installed in a ROS overlay. An extensive tutorial on rosws can be found here.
Creating a new workspace
The following command creates a new workspace in ~/fuerte_workspace which extends the set of packages installed in /opt/ros/fuerte:
rosws init ~/fuerte_workspace /opt/ros/fuerte
Note: rosws is part of the rosinstall package, which is not installed by default. The following command downloads it using the Ubuntu package manager:
sudo apt-get install python-rosinstall
Creating a sandbox directory for new packages
New packages need to be put in a path that is in the variable ROS_PACKAGE_PATH. All directories that are managed by rosws, i.e. that have been added using rosws are automatically added to the ROS_PACKAGE_PATH when the file setup.bash of the corresponding workspace is sourced. Although new packages should always be put in repositories that have been installed using rosws, it can be very convenient to have a sandbox directory where for instance packages created during the tutorials can be put without requiring any additional rosws commands. For that we create a new directory sandbox and add it to the hidden .rosinstall file with rosws:
mkdir ~/fuerte_workspace/sandbox rosws set ~/fuerte_workspace/sandbox
Every time the entries in the workspace change, it is necessary to re-source ~/fuerte_workspace/setup.bash to make sure that the updated ROS_PACKAGE_PATH is used.
source ~/fuerte_workspace/setup.bash
It is very common to replace the line source /opt/ros/fuerte/setup.bash to source the setup.bash in ~/fuerte_workspace or whichever workspace you use most often.
A more complete ROS Workspace tutorial can be found here.
Confirmation
To confirm that your package path has been set, echo the ROS_PACKAGE_PATH variable.
$ echo $ROS_PACKAGE_PATH
You should see something similar to:
/home/your_user_name/fuerte_workspace/sandbox:/opt/ros/fuerte/share:/opt/ros/fuerte/stacks
Now that your environment is setup, continue with the ROS file system tutorial.
Video Demonstration
Watch the video below to have more explanation on Custom Workspace and Package Creation with step by step guide .
