<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>rosws ROS Tutorial — rosinstall 0.6 documentation</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/print.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '0.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/theme_extras.js"></script>
<link rel="top" title="rosinstall 0.6 documentation" href="index.html" />
<link rel="next" title="rosinstall file format" href="rosinstall_file_format.html" />
<link rel="prev" title="rosws Tutorial" href="rosws_tutorial.html" />
</head>
<body>
<div class="header"><h1 class="heading"><a href="index.html">
<span>rosinstall 0.6 documentation</span></a></h1>
<h2 class="heading"><span>rosws ROS Tutorial</span></h2>
</div>
<div class="topnav">
<p>
«  <a href="rosws_tutorial.html">rosws Tutorial</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="rosinstall_file_format.html">rosinstall file format</a>  »
</p>
</div>
<div class="content">
<div class="section" id="rosws-ros-tutorial">
<span id="id1"></span><h1><a class="toc-backref" href="#id2">rosws ROS Tutorial</a><a class="headerlink" href="#rosws-ros-tutorial" title="Permalink to this headline">¶</a></h1>
<p>In this tutorial we will focus on how to use <tt class="docutils literal"><span class="pre">rosws</span></tt> for doing
development work for ROS. We will use the ROS fuerte distribution,
but you can use other distributions as well.</p>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#rosws-ros-tutorial" id="id2">rosws ROS Tutorial</a><ul>
<li><a class="reference internal" href="#introduction" id="id3">Introduction</a></li>
<li><a class="reference internal" href="#binding-a-workspace-to-a-ros-distribution" id="id4">Binding a workspace to a ROS distribution</a></li>
<li><a class="reference internal" href="#creating-a-sandbox-directory-for-new-packages" id="id5">Creating a sandbox directory for new packages</a></li>
<li><a class="reference internal" href="#adding-repositories-to-the-overlay" id="id6">Adding repositories to the overlay</a></li>
<li><a class="reference internal" href="#combining-merge-with-roslocate" id="id7">Combining merge with roslocate</a></li>
<li><a class="reference internal" href="#updating-repositories-in-an-overlay" id="id8">Updating repositories in an overlay</a></li>
<li><a class="reference internal" href="#developing-against-multiple-distributions" id="id9">Developing against multiple distributions</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h2><a class="toc-backref" href="#id3">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>The problem <tt class="docutils literal"><span class="pre">rosws</span></tt> tries to solve is that developers in robotics today
have to work with source code from multiple sources, multiple version
control systems, in multiple versions.</p>
<p>While many ROS libraries can be installed into system directories via
Debian packages or other system-based distribution mechanisms, many
developers have ROS libraries installed from source somewhere in their
home directory, and then made available at runtime by inclusion in the
<tt class="docutils literal"><span class="pre">ROS_PACKAGE_PATH</span></tt> environment variable.</p>
<p>By manipulating this environment variable, users can create their own
packages, install additional packages from source, or even shadow
installed packages with experimental versions.</p>
<p>There are a few ways to manage these “overlay” environments. A user
can manage <tt class="docutils literal"><span class="pre">ROS_PACKAGE_PATH</span></tt> environment variable by hand, but this
is cumbersome, can lead to confusion when switching environments, and
errors in this variable can easily break a user’s
environment. Alternatively, <tt class="docutils literal"><span class="pre">rosws</span></tt> (ROS Workspace) provides a
systematic method for managing package overlays in a user’s workspace.</p>
<p>When the developer makes changes to the source code and builds the
code, it is important that the builder uses the right ROS distribution
(e.g. electric vs fuerte) as well as the right version of the source code.</p>
<p>A builder will typically use environment variables such as <tt class="docutils literal"><span class="pre">CPATH,</span>
<span class="pre">LD_LIBRARY_PATH,</span> <span class="pre">PKG_CONFIG_PATH,</span></tt> etc. So the developer will have to
make sure that all those variables are all set correctly every time he
runs a build. Similarly, when the developer has a ROS package both
installed as a system library as well as local ‘overlay’ checkout
(with his modifications), it is important that the builder chooses the
right libraries for the build process, so the order of entries in the
environment variables also needs to be managed.</p>
<p>This is what <tt class="docutils literal"><span class="pre">rosws</span></tt> attempts to make easier for developers.</p>
</div>
<div class="section" id="binding-a-workspace-to-a-ros-distribution">
<h2><a class="toc-backref" href="#id4">Binding a workspace to a ROS distribution</a><a class="headerlink" href="#binding-a-workspace-to-a-ros-distribution" title="Permalink to this headline">¶</a></h2>
<p>The following command creates a new fuerte overlay workspace in ~/fuerte:</p>
<div class="highlight-python"><pre>$ rosws init ~/fuerte /opt/ros/fuerte</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This command does nothing else than to create the folder
<tt class="docutils literal"><span class="pre">~/fuerte</span></tt>, the files <tt class="docutils literal"><span class="pre">setup.bash</span></tt>, <tt class="docutils literal"><span class="pre">setup.sh</span></tt>, <tt class="docutils literal"><span class="pre">setup.zsh</span></tt>
and the hidden file <tt class="docutils literal"><span class="pre">.rosinstall</span></tt> in the directory <tt class="docutils literal"><span class="pre">~/fuerte</span></tt>.</p>
</div>
<p>We will use <tt class="docutils literal"><span class="pre">~/fuerte</span></tt> from now on. Other workspaces could be set
up similarly like this:</p>
<div class="highlight-python"><pre>$ rosws init ~/electric /opt/ros/electric
$ rosws init ~/electric_unstable /opt/ros/electric</pre>
</div>
<p>The next step is to source the <tt class="docutils literal"><span class="pre">setup.bash</span></tt> in <tt class="docutils literal"><span class="pre">~/fuerte</span></tt>:</p>
<div class="highlight-python"><pre>$ source ~/fuerte/setup.bash</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You can only source one workspace at a time. It is generally error
prone to switch from one workspace to another, this can cause
confusing errors. Prefer to keep the same workspace in the same
terminal. If you work with several workspaces, do not source any of
them in your <tt class="docutils literal"><span class="pre">.bashrc</span></tt>.</p>
</div>
<p>It is very common to replace the line <tt class="docutils literal"><span class="pre">source</span>
<span class="pre">/opt/ros/fuerte/setup.bash</span></tt> in the <tt class="docutils literal"><span class="pre">.bashrc</span></tt> to the command above,
so that whenever you create a new terminal, that environment is used.</p>
<p>You can verify the workspace using again <tt class="docutils literal"><span class="pre">rosws</span> <span class="pre">info</span></tt>:</p>
<div class="highlight-python"><pre>$ rosws info
workspace: ~/fuerte
ROS_ROOT: /opt/ros/fuerte/share/ros
Localname S SCM Version-Spec UID (Spec) URI (Spec) (https://...)
--------- - ---- ------------ ----------- -------------------------
/opt/ros/fuerte/stacks
/opt/ros/fuerte/share
/opt/ros/fuerte/share/ros</pre>
</div>
<p>You see in the second output line that there is a defined ROS_ROOT in
our workspace. The info table has many columns, all of which are
empty so far, we will get to that in a moment. You may notice that
<tt class="docutils literal"><span class="pre">rosws</span> <span class="pre">merge</span></tt> listed an added setup.sh, which is not shown in the
table, it is hidden because that entry is of no further interest to
you in your daily work.</p>
<p>The overlay now includes all packages that were installed in
<tt class="docutils literal"><span class="pre">/opt/ros/fuerte</span></tt>, which is by itself not very useful yet. However we
can now easily overlay installed packages.</p>
</div>
<div class="section" id="creating-a-sandbox-directory-for-new-packages">
<h2><a class="toc-backref" href="#id5">Creating a sandbox directory for new packages</a><a class="headerlink" href="#creating-a-sandbox-directory-for-new-packages" title="Permalink to this headline">¶</a></h2>
<p>New packages need to be put in a path that is in the variable
<tt class="docutils literal"><span class="pre">ROS_PACKAGE_PATH</span></tt>. All directories that are managed by <tt class="docutils literal"><span class="pre">rosws</span></tt>,
i.e. that have been added using <tt class="docutils literal"><span class="pre">rosws</span></tt> are automatically added to the
<tt class="docutils literal"><span class="pre">ROS_PACKAGE_PATH</span></tt> when the file <tt class="docutils literal"><span class="pre">setup.bash</span></tt> of the corresponding
workspace is sourced. Although new packages should always be put in
repositories that have been installed using <tt class="docutils literal"><span class="pre">rosws</span></tt>, 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 <tt class="docutils literal"><span class="pre">rosws</span></tt> commands. For that we create a new directory sandbox
and add it to the .rosinstall file:</p>
<div class="highlight-python"><pre>$ mkdir ~/fuerte/sandbox
$ rosws set ~/fuerte/sandbox</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Now, it is necessary to re-source <tt class="docutils literal"><span class="pre">~/fuerte/setup.bash</span></tt> to make
sure that the updated <tt class="docutils literal"><span class="pre">ROS_PACKAGE_PATH</span></tt> is used:</p>
<div class="last highlight-python"><pre>$ source ~/fuerte/setup.bash</pre>
</div>
</div>
<p>You can verify the workspace using again <tt class="docutils literal"><span class="pre">rosws</span> <span class="pre">info</span></tt>:</p>
<div class="highlight-python"><pre>$ cd ~/fuerte
$ rosws info
workspace: ~/fuerte
ROS_ROOT: /opt/ros/fuerte/share/ros
Localname S SCM Version-Spec UID (Spec) URI (Spec) (https://...)
--------- - ---- ------------ ----------- -------------------------
sandbox
/opt/ros/fuerte/stacks
/opt/ros/fuerte/share
/opt/ros/fuerte/share/ros</pre>
</div>
<p>As you can see the sandbox folder is at the top of the list. This is
important, as early entries overlay later entries. You can also check
the <tt class="docutils literal"><span class="pre">ROS_PACKAGE_PATH</span></tt>, it should be the same as the left column of
the table:</p>
<div class="highlight-python"><pre>$ echo $ROS_PACKAGE_PATH
/home/user/fuerte/sandbox:/opt/ros/fuerte/stacks:/opt/ros/fuerte/share:/opt/ros/fuerte/share/ros</pre>
</div>
<p>You can now create packages in the sandbox folder e.g. using
<tt class="docutils literal"><span class="pre">roscreate-pkg</span></tt>, and they will be found within the ROS_PACKAGE_PATH.</p>
</div>
<div class="section" id="adding-repositories-to-the-overlay">
<h2><a class="toc-backref" href="#id6">Adding repositories to the overlay</a><a class="headerlink" href="#adding-repositories-to-the-overlay" title="Permalink to this headline">¶</a></h2>
<p>Development normally happens in repositories and when installing
packages from source, they normally need to be checked out from a
repository and added to the <tt class="docutils literal"><span class="pre">ROS_PACKAGE_PATH</span></tt>. This can easily be
done using <tt class="docutils literal"><span class="pre">rosws</span></tt>. For instance, the following commands add the
development version of the stack turtlebot which is a Mercurial
repository:</p>
<div class="highlight-python"><pre>$ rosws set turtlebot --hg https://kforge.ros.org/turtlebot/turtlebot
$ rosws update turtlebot</pre>
</div>
<p>After re-sourcing setup.bash the new overlayed stack turtlebot should
be in your package path, i.e. <tt class="docutils literal"><span class="pre">roscd</span> <span class="pre">turtlebot</span></tt> should switch to the
directory <tt class="docutils literal"><span class="pre">~/fuerte/turtlebot</span></tt>.</p>
<p>If a stack is already installed in <tt class="docutils literal"><span class="pre">/opt/ros/fuerte</span></tt>, adding it
locally using <tt class="docutils literal"><span class="pre">rosws</span></tt> will shadow the existing stack, as long as
<tt class="docutils literal"><span class="pre">rosws</span></tt> info lists the stack earlier than the <tt class="docutils literal"><span class="pre">/opt/ros/fuerte</span></tt>
folders.</p>
<p>I.e. instead of the system installation, the stack in
<tt class="docutils literal"><span class="pre">~/ros_workspace</span></tt> will be used. That way, it is possible to edit
existing packages by cloning them in the overlay.</p>
<p>This makes it possible for you to use different workspaces with
different versions of the same libraries without much hassle. Also
this allows multiple users on a robot to each have their own version
of libraries.</p>
</div>
<div class="section" id="combining-merge-with-roslocate">
<h2><a class="toc-backref" href="#id7">Combining merge with roslocate</a><a class="headerlink" href="#combining-merge-with-roslocate" title="Permalink to this headline">¶</a></h2>
<p>A usecase that was considered in the design of <tt class="docutils literal"><span class="pre">rosws</span></tt> was to quickly
get ROS stacks into a workspace. The <tt class="docutils literal"><span class="pre">roslocate</span></tt> script uses an
online index to lookup stack or package source information by name.</p>
<p>We can pipe that information to <tt class="docutils literal"><span class="pre">rosws</span></tt> to add the definition to
our workspace.</p>
<p>As an example we will add the navigation stack. Just to show you what
is happening, we first call <tt class="docutils literal"><span class="pre">roslocate</span></tt>:</p>
<div class="highlight-python"><pre>$ roslocate info navigation
- hg:
local-name: navigation
meta:
repo-name: wg-kforge
uri: https://kforge.ros.org/navigation/navigation
version: default</pre>
</div>
<p>As you can see the command finds the required meta-information for a
stack or package by the given name <tt class="docutils literal"><span class="pre">navigation</span></tt>. We can call
<tt class="docutils literal"><span class="pre">roslocate</span> <span class="pre">info</span></tt> it again passing the output to “<tt class="docutils literal"><span class="pre">rosws</span> <span class="pre">merge</span> <span class="pre">-</span></tt>”:</p>
<div class="highlight-python"><pre>$ roslocate info navigation | rosws merge -
Performing actions:
Add new elements:
navigation hg https://kforge.ros.org/navigation/navigation default</pre>
</div>
<p>If you wanted, you could next checkout the source code calling <tt class="docutils literal"><span class="pre">rosws</span>
<span class="pre">update</span> <span class="pre">navigation</span></tt>.</p>
</div>
<div class="section" id="updating-repositories-in-an-overlay">
<h2><a class="toc-backref" href="#id8">Updating repositories in an overlay</a><a class="headerlink" href="#updating-repositories-in-an-overlay" title="Permalink to this headline">¶</a></h2>
<p><tt class="docutils literal"><span class="pre">rosws</span></tt> allows to update only a single repository or all repositories:</p>
<div class="highlight-python"><pre>$ rosws update navigation</pre>
</div>
<p>updates only the stack navigation while:</p>
<div class="highlight-python"><pre>$ rosws update</pre>
</div>
<p>updates all repositories.</p>
</div>
<div class="section" id="developing-against-multiple-distributions">
<h2><a class="toc-backref" href="#id9">Developing against multiple distributions</a><a class="headerlink" href="#developing-against-multiple-distributions" title="Permalink to this headline">¶</a></h2>
<p>As an example a developer might have the ROS navigation stack in versions
electric stable, electric unstable and fuerte on his harddisk.</p>
<p>(You may not have more than one distribution when you start learning
ROS, but the next distribution will come, so it’s good to be prepared.)</p>
<p>So as a developer, it is be good to create one local overlay
workspace for each distribution and variant to use:</p>
<div class="highlight-python"><pre>$ rosws init ~/fuerte /opt/ros/fuerte
$ rosws init ~/electric /opt/ros/electric
$ rosws init ~/electric_unstable /opt/ros/electric</pre>
</div>
<p>It is useful to use such folders to manage different source
checkouts of the same ROS package. Using the same folder and
switching versions is very prone to mistakes and not recommended.</p>
<p>You can use each of these folders as an independent workspace.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">It is generally not a good idea to change the distribution a ROS
workspace is bound to. This often leads to confusing error messages
because compiled files assume the wrong distribution.</p>
</div>
</div>
</div>
</div>
<div class="bottomnav">
<p>
«  <a href="rosws_tutorial.html">rosws Tutorial</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="rosinstall_file_format.html">rosinstall file format</a>  »
</p>
</div>
<div class="footer">
© Copyright 2011, Willow Garage.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
