<commit_before>.. _build_from_source_using_ros_catkin:

**************************************
Building Drake as a ROS Catkin Package
**************************************

.. _drake_catkin_instruction:

Introduction
============

The `Robot Operating System (ROS) <http://www.ros.org/>`_ provides a software
platform for conducting advanced robotics research and development. Since its
`creation in the mid 2000s <http://www.ros.org/history/>`_, ROS has
attained a `tremendous following <http://wiki.ros.org/Metrics>`_ due in part to
its integration of many infrastructure-level components that are important to
robotics and the increased collaborative potential resulting from platform
standardization. It is arguably among the most successful open source robotics
platforms to date in terms of fostering collaboration, research, and innovation
within robotics.


Drake can be configured to be a package within a ROS workspace. Instructions for
how to do this are given below. Before starting, ensure
`ROS is installed <http://wiki.ros.org/ROS/Installation>`_
and your public SSH key is
`added to your github account <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/>`_.

.. _drake_catkin_prerequisites:

Step 0: Install Prerequisites
=============================

Install
`Ubuntu 14.04.4 LTS (Trusty Tahr) <http://releases.ubuntu.com/14.04/>`_ and
`ROS Indigo <http://wiki.ros.org/indigo>`_. Other versions of the OS and ROS
may or may not work.

Install package ``ros-indigo-ackermann-msgs``, which is used by
software in `drake_ros_systems <https://github.com/RobotLocomotion/drake/tree/master/ros/drake_ros_systems>`_::

    sudo apt-get install ros-indigo-ackermann-msgs

Once the OS and ROS are installed, install
`Catkin Tools <http://catkin-tools.readthedocs.io/en/latest/>`_ by following
the instructions
`here <http://catkin-tools.readthedocs.io/en/latest/installing.html>`_.
We use ``catkin_tools`` due to its better support building pure CMake packages
alongside Catkin packages.

.. _drake_catkin_create_workspace_directories:

Step 1: Create Directories for Holding a ROS Catkin Workspace
=============================================================

This assumes you want to create a *new* ROS workspace
in ``~/dev`` called ``drake_catkin_workspace``. The commands below can be
customized with a different workspace name and location.

If you already have a ROS Catkin workspace and simply want to add Drake as a
package within it, you can skip this step and go straight to
:ref:`drake_catkin_add_repos`.

Execute the following commands to create a directory structure for holding the
ROS workspace::

    mkdir -p ~/dev/drake_catkin_workspace/src

.. _drake_catkin_add_repos:

Step 2: Add ``drake`` and ``drake_ros_integration`` to the Workspace
====================================================================

Add ``drake`` and ``drake_ros_integration`` to the workspace::

    cd ~/dev/drake_catkin_workspace/src
    git clone <EMAIL>:RobotLocomotion/drake.git
    ln -s drake/ros drake_ros_integration

Note that ``drake_ros_integration`` is a symbolic link. This allows us to keep
everything in Drake's main repository without needing to completely reorganize
the files in it.

.. _drake_catkin_build_workspace:

Step 3: Build the Workspace
===========================

Execute the following commands to build the workspace::

    cd ~/dev/drake_catkin_workspace
    source /opt/ros/indigo/setup.bash
    catkin init
    catkin build -DCMAKE_BUILD_TYPE:STRING=RelWithDebInfo

There are numerous optional flags that can be included after the ``catkin build``
command listed above. The example above includes the build type flag that
specifies the build should be ``RelWithDebInfo``. Alternative include
``Release`` and ``Debug``. Another flag is ``-DDISABLE_MATLAB=TRUE``, which
disables MATLAB support. This may be useful if you have MATLAB installed but
don't have access to a license server. There are many additional command line
flags that, for example, enables support for certain optimizers like
`SNOPT <http://www.sbsi-sol-optimize.com/asp/sol_product_snopt.htm>`_.
For a full list of these optional command line flags, see the variables defined
in ``~/dev/drake_catkin_workspace/src/drake/CMakeLists.txt``.

Note also that Catkin by default performs a multi-threaded build.
If your computer does not have sufficient computational resources to support
this, you can add a ``-j1`` flag after the ``catkin_make`` command to force a
single-threaded build, which uses fewer resources.

Later, if you want to do a clean build, you can execute::

    cd ~/dev/drake_catkin_workspace
    catkin clean
    cd src/drake
    git clean -fdx
    cd ~/dev/drake_catkin_workspace
    source /opt/ros/indigo/setup.bash
    catkin build

.. _drake_catkin_run_unit_tests:

Step 4: Run Unit Tests<commit_msg>Added missing --cmake-args to ROS build instructions.<commit_after>.. _build_from_source_using_ros_catkin:

**************************************
Building Drake as a ROS Catkin Package
**************************************

.. _drake_catkin_instruction:

Introduction
============

The `Robot Operating System (ROS) <http://www.ros.org/>`_ provides a software
platform for conducting advanced robotics research and development. Since its
`creation in the mid 2000s <http://www.ros.org/history/>`_, ROS has
attained a `tremendous following <http://wiki.ros.org/Metrics>`_ due in part to
its integration of many infrastructure-level components that are important to
robotics and the increased collaborative potential resulting from platform
standardization. It is arguably among the most successful open source robotics
platforms to date in terms of fostering collaboration, research, and innovation
within robotics.


Drake can be configured to be a package within a ROS workspace. Instructions for
how to do this are given below. Before starting, ensure
`ROS is installed <http://wiki.ros.org/ROS/Installation>`_
and your public SSH key is
`added to your github account <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/>`_.

.. _drake_catkin_prerequisites:

Step 0: Install Prerequisites
=============================

Install
`Ubuntu 14.04.4 LTS (Trusty Tahr) <http://releases.ubuntu.com/14.04/>`_ and
`ROS Indigo <http://wiki.ros.org/indigo>`_. Other versions of the OS and ROS
may or may not work.

Install package ``ros-indigo-ackermann-msgs``, which is used by
software in `drake_ros_systems <https://github.com/RobotLocomotion/drake/tree/master/ros/drake_ros_systems>`_::

    sudo apt-get install ros-indigo-ackermann-msgs

Once the OS and ROS are installed, install
`Catkin Tools <http://catkin-tools.readthedocs.io/en/latest/>`_ by following
the instructions
`here <http://catkin-tools.readthedocs.io/en/latest/installing.html>`_.
We use ``catkin_tools`` due to its better support building pure CMake packages
alongside Catkin packages.

.. _drake_catkin_create_workspace_directories:

Step 1: Create Directories for Holding a ROS Catkin Workspace
=============================================================

This assumes you want to create a *new* ROS workspace
in ``~/dev`` called ``drake_catkin_workspace``. The commands below can be
customized with a different workspace name and location.

If you already have a ROS Catkin workspace and simply want to add Drake as a
package within it, you can skip this step and go straight to
:ref:`drake_catkin_add_repos`.

Execute the following commands to create a directory structure for holding the
ROS workspace::

    mkdir -p ~/dev/drake_catkin_workspace/src

.. _drake_catkin_add_repos:

Step 2: Add ``drake`` and ``drake_ros_integration`` to the Workspace
====================================================================

Add ``drake`` and ``drake_ros_integration`` to the workspace::

    cd ~/dev/drake_catkin_workspace/src
    git clone <EMAIL>:RobotLocomotion/drake.git
    ln -s drake/ros drake_ros_integration

Note that ``drake_ros_integration`` is a symbolic link. This allows us to keep
everything in Drake's main repository without needing to completely reorganize
the files in it.

.. _drake_catkin_build_workspace:

Step 3: Build the Workspace
===========================

Execute the following commands to build the workspace::

    cd ~/dev/drake_catkin_workspace
    source /opt/ros/indigo/setup.bash
    catkin init
    catkin build --cmake-args -DCMAKE_BUILD_TYPE:STRING=RelWithDebInfo

There are numerous optional flags that can be included after the ``catkin build``
command listed above. The example above includes the build type flag that
specifies the build should be ``RelWithDebInfo``. Alternative include
``Release`` and ``Debug``. Another flag is ``-DDISABLE_MATLAB=TRUE``, which
disables MATLAB support. This may be useful if you have MATLAB installed but
don't have access to a license server. There are many additional command line
flags that, for example, enables support for certain optimizers like
`SNOPT <http://www.sbsi-sol-optimize.com/asp/sol_product_snopt.htm>`_.
For a full list of these optional command line flags, see the variables defined
in ``~/dev/drake_catkin_workspace/src/drake/CMakeLists.txt``.

Note also that Catkin by default performs a multi-threaded build.
If your computer does not have sufficient computational resources to support
this, you can add a ``-j1`` flag after the ``catkin_make`` command to force a
single-threaded build, which uses fewer resources.

Later, if you want to do a clean build, you can execute::

    cd ~/dev/drake_catkin_workspace
    catkin clean
    cd src/drake
    git clean -fdx
    cd ~/dev/drake_catkin_workspace
    source /opt/ros/indigo/setup.bash
    catkin build

.. _drake_catkin_run_unit_tests:

Step 4: Run Unit Tests
{'fraction_non_alphanumeric': 0.130568356374808, 'fraction_numerical': 0.0038914490527393753, 'mean_word_length': 4.93677811550152, 'pattern_counts': {'":': 0, '<': 27, '<?xml version=': 0, '>': 27, 'https://': 4, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4485961', 'n_tokens_mistral': 2943, 'n_tokens_neox': 2719, 'n_words': 1072}