<<TableOfContents(3)>>

= Migration guide =

In ROS Fuerte, includes and library exports were cleaned up.  This cleanup may cause regressions in your builds due to missing linker calls that were being accidentally inherited, or missing includes.

ROS Fuerte also rosdep 2, which '''no longer processes <stack>/rosdep.yaml''' files.  Please see:

 * [[http://ros.org/doc/api/rosdep/html/|rosdep 2 documentation]]
 * [[http://ros.org/reps/rep-0125.html|REP 125: rosdep 2 ]]

##== Known issues ==

##These are known issues that do not require migration on your part.


== Common errors ==

There are two categories of errors in general:

 1. Code depends on deprecated libraries/functions that were removed in Fuerte (e.g. Eigen, tinyxml, yaml_cpp).  These deprecations were already noted on the relevant package/stack wiki pages, so please check there first for migration guides.  

 2. New ROS core libraries are less promiscuous exporting compiler flags.


For both of these categories, ''any changes you make to your code are backwards-compatible with Electric''.

Removed packages:

 * [[eigen]]
 * [[tinyxml]]
 * [[yaml_cpp]]

Likely to be removed:

 * [[opencv2]]

Stacks with removed dependencies:

 * [[common]] (no longer forwards dependencies for nodelet_core, bond_core, pluginlib, filters, and xacro)

=== Bullet Datatypes Changed ===
If you are using tf or bullet datatypes please read the [[geometry/bullet_migration| Bullet Fuerte Migration Guide]]

=== Eigen can't be found ===

==== If you're using Eigen directly in your code ====
Starting with Fuerte, the new pattern to find Eigen in a CMakeLists.txt file is:
{{{
find_package(Eigen REQUIRED)
include_directories(${EIGEN_INCLUDE_DIRS})
add_definitions(${EIGEN_DEFINITIONS})
}}}
This code relies on Eigen .cmake files that are distributed with catkin (specifically, `/opt/ros/fuerte/share/catkin/cmake/Modules/eigen-*`).

==== If you're exporting headers that use Eigen to others ====
If you provide headers included by code in other packages, and those headers use Eigen, then you must also export the flags to find Eigen.  Do that by adding {{{`pkg-config --cflags eigen3`}}} to the exported `cflags` in your `manifest.xml`.  E.g., your `manifest.xml` might contain something like this:
{{{
 <export>
    <cpp cflags="`pkg-config --cflags eigen3` -I${prefix}/include `rosboost-cfg --cflags`" 
         lflags="-Wl,-rpath,${prefix}/lib -L${prefix}/lib -lplanning_models"/>
  </export>
}}}

=== Error 'ROS_WARN' was not declared in this scope (or 'ROS_INFO' or 'ROS_DEBUG') ===

Source code needs:

{{{
   #include <ros/console.h>
}}}

=== Error 'ROS_ASSERT' was not declared in this scope ===

Source code needs:

{{{
   #include <ros/assert.h>
}}}

=== Errors with ROS_STATIC_ASSERT ===

Source code needs:

{{{
   #include <ros/static_assert.h>
}}}

=== Errors linking boost (e.g. with Boost signals or thread) ===

If you see something like this:
{{{
/usr/bin/ld: note: 'boost::signals::trackable::~trackable()' is defined in DSO /usr/lib/libboost_signals.so.1.46.1 so try adding it to the linker command line
}}}
then in your `CMakeLists.txt`, you need to explicitly link to the Boost libraries you use, e.g.:
{{{
   # Put this line before the executable or library:
   rosbuild_add_boost_directories()
   # Existing code:
   rosbuild_add_executable(my_target my_srcs....)
   # Put this line after the executable or library:
   rosbuild_link_boost(my_target signals)
}}}
The two most commonly missing Boost libraries are `signals` and `thread`.  Note that this error will only occur on systems with relatively strict linkers; in particular you will see it on Oneiric but not Lucid.

Documentation:

 * [[CMakeLists#rosbuild_add_boost_directories]]
 * [[CMakeLists#rosbuild_link_boost]]



=== Errors linking log4cxx ===
 
Add to your `CMakeLists.txt`:

{{{
   find_library(LOG4CXX_LIBRARY log4cxx)
   target_link_libraries(my_target ${LOG4CXX_LIBRARY})
}}}


=== Errors linking -lros ===

Do not link against `-lros` directly.  It doesn't exist in Fuerte, and anything in Electric that linked against it directly was doing so incorrectly.

=== ERROR: Stack's declared dependencies are missing calculated dependencies: actionlib ===

Edit your `stack.xml` to add:
{{{
  <depend stack="actionlib" />
}}}

You should also remove the `<depend stack="common" />` line that is probably there as well.

=== error: XXX has no member named 'set_YYY_size' (or 'get_YYY_size') ===
This is a long-deprecated and now removed part of the C++ message API.  Switch to using the standard `vector` API:
{{{
  // Change from this:
  // my_msg.set_foo_size(42);
  // To this:
  my_msg.foo.resize(42);

  // Change from this:
  // sz = my_msg.get_foo_size(42);
  // To this:
  sz = my_msg.foo.size();
}}}

In sed:
{{{
s/set_\(.*\)_size/\1.resize
s/get_\(.*\)_size/\1.size
}}}

=== Errors about roslib::Header (includes, symbol references) ===
Replace this:
{{{
#include <roslib/Header.h>
}}}
with this:
{{{
#include <std_msgs/Header.h>
}}}
And replace references to:
{{{
roslib::Header
}}}
with:
{{{
std_msgs::Header
}}}


=== Errors with roslaunch <machine> tag ===

The [[roslaunch/XML/machine|<machine>]] tag in roslaunch was changed to accomodate environment setup differences caused by migrating to a FHS layout in `/opt/ros/fuerte`.  These changes are not backwards-compatible.

Environment variables are now set via an `env-loader` script.  You can no longer set `ros-root` and `ros-package-path` attributes, or assign [[roslaunch/XML/env|<env>]] tags to a [[roslaunch/XML/machine|<machine>]].  Instead, the `env-loader` script on the remote machine does all environment configuration.

Example (note `env-loader` property):

{{{
<machine name="..." address="..." env-loader="/opt/ros/fuerte/env.sh" />
}}}
If the `env-loader` property is not present, it will be inferred from the local environment.  

=== No more roscreate-stack ===

roscreate-stack is no longer available as it cannot work correctly with low-level dependencies.  You will have to manually maintain stack.xml dependencies. More info on the [[http://lists.ros.org/lurker/message/20120225.192215.fd9819dc.en.html|ros-users mailing list]].


=== Errors switching between Fuerte and other ROS releases ===
Some things were moved around in Fuerte, and some environment variables are being set that weren't being set before.  So if you switch your environment between Fuerte and something else (e.g., Electric), you might have trouble.

Current best practice: '''Don't switch environments. Always start with a fresh shell.'''

We're working on fixes for each problem that comes up.  Known issues include:
 * After switching from Fuerte to Electric: `rosbuild` finds the Fuerte version of `rospack`, which can result in build output like this: {{{
[rosbuild] Including /opt/ros/electric/stacks/ros_comm/clients/cpp/roscpp/cmake/roscpp.cmake
CMake Error at /opt/ros/electric/ros/core/roslang/cmake/roslang.cmake:26 (message):
  Cannot include non-existent exported cmake file
  -I/opt/ros/electric/stacks/ros_comm/clients/cpp/roscpp/msg_gen/cpp/include
Call Stack (most recent call first):
  /opt/ros/electric/ros/core/rosbuild/public.cmake:385 (include)
  CMakeLists.txt:12 (rosbuild_init)
}}}  If this happens, you should: {{{
unset CMAKE_PREFIX_PATH
}}} [[https://code.ros.org/trac/ros/ticket/3831|(ticketed)]]
 * After switching from Electric to Fuerte: tools that are no longer in `$ROS_ROOT/bin` are found in older installations, including `rosdep`.  Best to start with a fresh shell.  ([[https://code.ros.org/trac/ros/ticket/3832|ticketed]])

=== Errors releasing into Fuerte ===
First of all, be sure that you're following the [[fuerte/release|Fuerte release instructions]], which prescribe the use of a new release script: `rosrelease-legacy`. Second, stay up-to-date with that release script: {{{
sudo pip install -U rosrelease
}}} Important fixes are being made quickly.

If you see this: {{{
ERROR: stack depends on [pcl], which is not in a stack
}}} then update `rosrelease` (see above).


=== Errors finding rosemacs ===

[[rosemacs]] is now distributed separately from the core ROS codebase. This will enable your Emacs experience to improve regardless of which version of ROS you are using.

== Stack-fixing quickstart ==
How to get the stuff you need to reproduce and fix bugs.  Let's say you want to debug a broken stack called STACK.

 1. If possible, work on an Oneiric machine.  The linker is much stricter there than on Lucid, and many problems are linker-related.
 1. Update your list of debs: {{{
sudo apt-get update}}}
 1. Upgrade your debs (just in case you have an old install lying around): {{{
sudo apt-get upgrade}}}
 1. Install the dependencies of STACK.  Usually, the dependencies are already available in deb form, in which case you should install the `ros-fuerte-` debs that STACK requires.  If you don't know the requirements set, you can try installing everything: {{{sudo apt-get install 'ros-fuerte-*'}}}.  Sometimes, you may need to pull dependencies from source. See below for more on this.
 1. Source the fuerte configuration file: {{{
source /opt/ros/fuerte/setup.sh}}}
 1. Create a workspace to debug in: {{{
mkdir work
cd work}}}
 1. Checkout the broken stack from source: {{{
rosco --distro=unstable --dev STACK}}}.  At this point, if you need other stacks from source (because they're not available in deb form, or because you need a newer version than what's available in the debs), use `rosco` in a similar manner to get them into `work`. 
 1. Add your workspace to ROS_PACKAGE_PATH: {{{
export ROS_PACKAGE_PATH=`pwd`:$ROS_PACKAGE_PATH}}}
 1. Double-check that STACK's dependencies are satisfied: {{{
rosstack deps STACK
}}} If you see errors, you need to install more stacks, via `apt-get` and/or `rosco`.
 1. Try to build your stack: {{{
rosmake STACK}}}
 1. Fix what is broken.
 1. Do a new release of STACK into fuerte.  The old `release/create.py` script doesn't work atop fuerte, so you'll need to follow the new [[release/Releasing/fuerte]] instructions.

== Errors on non-Ubuntu platforms ==

==== Errors linking PCL, swig-wx, and opencv ====

ROS uses a modified version of PCL and swig-wx.  Most system dependencies are equivalent, but PCL shares message data structures and thus requires alternate build flags to be compatible with ROS.  Similarly, the swig-wx contains necessary patches; swig-wx will disappear in Groovy and so is a transitional issue.  

The current workaround is the build and install from the trees that ROS uses here:

https://github.com/wg-debs

Note: make sure to install into /opt/ros/fuerte (CMAKE_INSTALL_PREFIX), enable ROS (e.g. in pcl using the ccmake option USE_ROS), and remove the --install-layout=deb configuration option (SETUPTOOLS_ARG_EXTRA)

OpenCV should be compatible with normal OpenCV packaging, though ROS packages that explicitly depend on 'opencv2' may need this dependency to be removed (this is a deprecation/migration issue).