This is a layer to provide ROS in an openembedded linux system.
Currently, this layer is still under development and not fully functional.

PURPOSE of this document:
  This document describes
  - the installation, use and content of the git repository meta_ros 
  - milestones, the open issues and how some issues have been resolved. 
  - license information and origin of redistributed files


INSTALLATION:

  The repository only contains a layer for ros that builds on top of the existing openembedded core layer.
  You can download the yocto poky-danny-8.0 archive, but then you should update the distutils.bbclass,
  and maybe also the url of libarchive.
  To install, unpack http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/poky-danny-8.0.tar.bz2 into a directory <dir>.
  
  In the directory of the layers, clone this repository into the subdirectory meta-ros. 
  Add the meta-ros directory to your local bblayers.conf file.


USE for native compilation on the VM (milestone M1):
  The commands
    source oe-init-build-env
    bitbake core-image-ros
  builds our specifically configured linux image.
  
  With `runqemu qemux86-64 qemuparams="-m 2048" core-image-ros` the linux image runs within a virtual machine with 2048 MB of memory.
  We assumed that this is running on and compiled for an x86-64 architecture. For other architectures, some settings must be adjusted.
  
  On the host system, run fetch_ros.sh in a fresh directory, e.g. ~/ros-repos/.
  It clones all ros repositories locally.
  After starting the virtual machine, copy the installation script from the host system to the home directory with scp.
  
    scp lukas@192.168.7.1:/<location of repository>/install.sh .

  Adjust configuration in install.sh and then run

    sh ./install.sh
  
  The installation script installs ros and starts roscore.

USE for cross-compilation (milestone M2):
   
  source oe-init-build-env
  bitbake ros

  momentarily fails at some point (see CURRENT STATE)


CONTENT of the repository:

  README                                                   this README file, which contains all important information
  COPYING.MIT
  conf/layer.conf                                          configuration file for this layer
  install.sh                                               installation script that runs within the virtual machine
  recipes-core/images/core-image-ros.bb                    recipe for our own core image (derived from core-image-minimal)
  recipes-devtools/python/python-pyyaml_3.10.bb            recipe for pyyaml python library
  recipes-devtools/python/python-rospkg_1.0.15.bb          recipe for rospkg tool
  recipes-devtools/python/python-empy_3.3.bb               recipe for empy python library
  recipes-devtools/python/python-nose_1.2.1.bb             recipe for nose python library
  recipes-devtools/python/python-rosinstall_0.6.21.bb      recipe for rosinstall tool
  recipes-devtools/python/python-pyyaml-native_3.10.bb     native recipes for cross-compilation
  recipes-devtools/python/python-rospkg-native_1.0.15.bb
  recipes-devtools/python/python-empy-native_3.3.bb
  recipes-devtools/python/python-nose-native_1.2.1.bb
  recipes-devtools/python/python-setuptools_0.6c11.bb      setuptools recipe originated from oe-core
  recipes-devtools/log4cxx                                 recipes and patches for log4cxx 0.10.0
  recipes-devtools/log4cxx/log4cxx_0.10.0.bb
  recipes-devtools/log4cxx/log4cxx/0001-log4cxx_0-10-0_add-missing-includes.patch
  recipes-devtools/log4cxx/log4cxx/0003-log4cxx-0.10.0-add_stdio_header.patch
  recipes-devtools/log4cxx/log4cxx/0002-Remove-duplicates-from-makefile.patch
  recipes-ros/ros/ros.bb                                   recipe for ros (incomplete)
  recipes-ros/ros/ros/fuerte-ros-base.rosinstall           the .rosinstall file to download ros
  classes/distutils.bbclass                                distutils recipe originated from oe-core (patch submitted to oe-core and accepted)
  classes/easyinstall.bbclass                              adjustments for easyinstall


MILESTONES

  M1: basic image with dev-tools (make, cmake, ...) and ROS compiles natively in the virtual machine
  M2: Linux+ROS System can be built completely with bitbake (no compilation and installing in the virtual machine)
  M3: Linux+ROS System with configured kernel (e.g. RT-Linux, System-D) that meets real-time and safety requirements 

RESOLVED ISSUES for M1:

  - recipes for python-pyyaml and python-rospkg create invalid shell scripts (header line refers to python-native instead of python.)
    RESOLVED by patching distutils class--has be committed to oe-core.
  - recipe for log4cxx requires another patch.
    RESOLVED by providing patch 0003 in recipe
  - Compilation with make fails in the virtual machine because of insufficient memory during compilation.
    RESOLVED by increasing memory.
  
OPEN ISSUES for M1:

  - python-setuptools requires some python-modules at run-time.
    TEMPORARILY RESOLVED by adding all python-modules in the image
    SHOULD BE RESOLVED by creating an appropriate patch for python-setuptools and contributing to openembedded-core
  - rospkg modules are not found when runnning python.
    TEMPORARILY RESOLVED by installing natively in the virtual machine
    CAUSE of PROBLEM: must add /usr/lib/python2.7/site-packages/rospkg-1.0.15-py2.7.egg to PYTHON_PATH (sys.path)
    In the usual setting, this is done by adding rospkg-1.0.15-py2.7.egg to the easy-install.pth
    However, the distutils class removes the created easy-install.pth before packaging.
    Modifying the class, to not remove the easy-install.pth does not solve the issue, because
    also the python-setuptools must add an entry to easy-install.pth
    This can be only solved by providing a general merge mechanism for the easy-install.pth file.
    Implementing this should not be difficult because the format of this file is very easy, and
    the pathes can be simply accumulated.
    FIRST TEMPORARY SOLUTION: we simply write the easy-install.pth file in the rootfs task of the image generation.
    SECOND SOLUTION: implemented behavior described above
    THIRD SOLUTION: uses the dist_utils argument to use traditional packaging mechanism and avoid .egg files at all (suggested by Ross Burton)

OPEN ISSUES for M2:
  - understand what rosinstall actually does
  - how fetch from multiple git repositories in one recipe?


CURRENT STATE:

`bitbake ros` fails with:

> CMake Error at catkin/cmake/find_program_required.cmake:5 (message):
>  check_test_ran.py not found
> Call Stack (most recent call first):
>  ../catkin/CMakeFiles/tests.cmake:31 (find_program_required)
>  ../catkin/CMakeFiles/tests.cmake:41 (catkin_initialize_tests)
>  catkin/cmake/all.cmake:54 (include)
>  catkin/CMakeLists.txt:12 (include)
>
>
>
> -- Configuring incomplete, errors occurred!
>
>
> ERROR: Function failed: do_configure (see /home/lukas/NEW/poky-danny-8.0/build/tmp/work/i586-poky-linux/ros-1.0-r0/temp/log.do_configure.9702 for further information)
> ERROR: Logfile of failure stored in: /home/lukas/NEW/poky-danny-8.0/build/tmp/work/i586-poky-linux/ros-1.0-r0/temp/log.do_configure.9702


LICENSE

All metadata is MIT licensed unless otherwise stated. Source code included
in tree for individual recipes is under the LICENSE stated in each recipe
(.bb file) unless otherwise stated.

This README document is Copyright (C) 2012 BMW Car IT GmbH.


REDISTRIBUTIONS

The log4cxx recipe originated from the recipe in the OpenEmbedded (Classic) Development
  (cf. http://cgit.openembedded.org/openembedded/tree/recipes/log4cxx)
  licensed with the MIT License.
The core-image-ros recipe originated from the core-image-minimal recipe in OpenEmbedded Core
  (cf. http://cgit.openembedded.org/openembedded-core/tree/meta/recipes-core/images/core-image-minimal.bb)
  licensed with the MIT License.
The distutils class originated the distutils class in OpenEmbedded Core
  (cf. http://cgit.openembedded.org/openembedded-core/tree/meta/classes/distutils.bbclass)
  licensed with the MIT License.

The modified files are redistributed here under the same MIT License.