====== Recommended procedure for installing ROS ======

The following instructions are meant as guideline which tutorials to follow in order to get a well-configured ROS workspace that can be used to run and develop the IAI software.

===== Install ROS core system =====
It is strongly recommended to use Ubuntu Linux as operating system. While other OSs may work, they will more manual adaptations may be needed that require good knowledge of Linux and build systems.

Follow the [[http://www.ros.org/wiki/fuerte/Installation/Ubuntu|main installation tutorial for your distribution]] and choose the [[http://www.ros.org/wiki/ROS/Installation/UbuntuMirrors|mirror from Freiburg]] for downloading the packages. It's much faster in Europe than the main ros.org server. To get a good first set of ROS packages, it is recommended to install the //ros-fuerte-desktop-full// package.

After the installation, you need to initialize your rosdep rules. These rules specify system dependencies of ROS packages; the rosdep tool can be used to automatically resolve them.
  sudo rosdep init
===== Setup ROS workspace ('overlay') =====

The ROS core components are installed as binary .deb packages into /opt/ros and **should not be edited**. Every ROS package that you are developing on should reside in your **ROS workspace**, a directory in your home directory.

ROS packages are found by the ROS_PACKAGE_PATH environment variable that is evaluated from the beginning, i.e. ROS uses the first package with the given name that is found in the directories listed in the ROS_PACKAGE_PATH. This means that you can override the system packages by putting (newer) versions of them into your local ROS workspace folder, which is always more upfront in the ROS_PACKAGE_PATH.

The following tutorials introduces the rosws tool that makes it easy to create an overlay and that manages the ROS_PACKAGE_PATH for you. Please read both before setting up your environment.
 
  * http://www.ros.org/wiki/ROS/Tutorials/InstallingandConfiguringROSEnvironment
  * http://www.ros.org/wiki/fuerte/Installation/Overlays



===== Install IAI software components =====

It is recommended to install the ROS stacks for which .deb packages exist first, also because this is the easiest way to get all system dependencies installed:

  sudo aptitude install ros-fuerte-knowrob ros-fuerte-ias-common

Copy the following [[http://www.ros.org/doc/independent/api/rosinstall/html/|rosinstall rules]] into a text file in your ROS workspace, e.g. yourname.rosinstall.
<code>
  - git: {local-name: stacks/cram_core, uri: 'git://github.com/cram-code/cram_core.git'}
  - git: {local-name: stacks/cram_highlevel, uri: 'git://github.com/cram-code/cram_highlevel.git'}
  - git: {local-name: stacks/cram_pr2, uri: 'git://github.com/cram-code/cram_pr2.git'}
  - git: {local-name: stacks/cram_physics, uri: 'git://github.com/cram-code/cram_physics.git'}
  - git: {local-name: stacks/knowrob, uri: 'git://github.com/knowrob/knowrob.git'}
  - git: {local-name: stacks/knowrob_addons, uri: 'git@github.com:knowrob/knowrob_addons.git'}
  - git: {local-name: stacks/knowrob_gui, uri: 'git@github.com:knowrob/knowrob_gui.git'}
  - git: {local-name: stacks/knowrob_human, uri: 'git@github.com:knowrob/knowrob_human.git'}
  - git: {local-name: stacks/knowrob_tutorials, uri: 'git@github.com:knowrob/knowrob_tutorials.git'}
</code>

You can then install the respective ROS stacks into your workspace using
  rosws merge yourname.rosinstall
  rosws update

Note: As an alternative to creating and merging a rosinstall file into your workspace you can also manually add each one at a time using the command 'rosws set ...'. Usage of this command is shown in the next section.

To compile the software, please refer to the next section for information about how to install the required ROS and system dependencies.

===== General workflow for compiling ROS stacks =====

ROS provides a clear way of specifying and resolving dependencies. If you download a new ROS stack "your_stack" you can compile it using the following procedure:

Add the stack to your ROS workspace (choose the respective version control system):

  EITHER:
  rosws set stacks/your_stack --git git://github.com/code_iai/your_stack.git
  OR:
  rosws set stacks/your_stack --svn http://svn.code.sf.net/p/tum-ros-pkg/code/your_stack

Check out the sources

  rosws update

Resolve system dependencies

  rosdep update
  rosdep install your_stack


Check if all ROS package dependencies are available (should list all dependencies and not return any errors)

  rospack depends your_stack
  
Locate and install missing ROS dependencies: For each package that rospack complained about do

  # Find out which stack the package is in, either using the ROS wiki or with
  roslocate describe <pkg_name>
    
  # Let us assume the package pkg_name is in stack stack_name.

  # Check if there is a .deb package for the stack. They are called 
  # ros-<distro>-<stackname>, while all underscores in the stackname 
  # are replaced by hyphens (e.g. stack_name becomes ros-fuerte-stack-name). 
  # You can search for this package using 
  
  apt-cache search ros-fuerte-stack-name
  
  # and install with
  
  sudo apt-get install ros-fuerte-stack-name
  
  # If there is no .deb package, install the stack from source using 
  
  roslocate info stack_name | rosws merge -
  
  # Remember to also check for system dependencies of the newly-added stack stack_name

Now everything should be resolved and you are ready to compile. The //rosmake// command automatically compiles all dependencies and the package or stack given as argument. If later on you already have compiled all dependencies and just updated the package itself, it's also safe to just call //make// in that package, which does not re-build the dependencies (and is therefore faster).

  rosmake your_stack