Component Packages

Creating a new package

This is extremely easily done with the orocreate-pkg script, see Getting started.

Building and Using packages

This section only applies to packages that can be built, ie that contain a Makefile, CMakeLists.txt, configure or any other file that describes how to build it.

You can use packages in two ways:

  • built in-place (the ROS way)
  • installed (the traditional way, used by autoproj)

Using packages in-place [ROS]

For using this method, you need the ROS tools (roscd, rospack, rosmake,...) to manage your packages and your package directories must be underneath the ROS_PACKAGE_PATH. Orocos will choose this method automatically when the 'ROS_ROOT' environment variable exists. The orogen tools do not support in-place packages. Orogen needs the 'make install' step after a package has been built (see Using Installed Packages below).

Layout

When building a package in-place, it needs a top-level Makefile which creates a build directory, builds the libraries and puts them like this

# User provided files:
# Package directory:
.../packagename/manifest.xml, Makefile, CMakeLists.txt,...
# Sources:
.../packagename/src/*.cpp
# Headers:
.../packagename/include/packagename/*.hpp
 
# Build results:
# Built Component libraries for 'packagename':
.../packagename/lib/orocos/gnulinux/*.so|dll|...
# Built Plugin libraries for 'packagename':
.../packagename/lib/orocos/gnulinux/plugins/*.so|dll|...
# Type libraries for 'packagename':
.../packagename/lib/orocos/gnulinux/types/*.so|dll|...
# Build information for 'packagename':
.../packagename/packagename-gnulinux.pc

For allowing multi-target builds, the libraries are put in thelib/orocos/targetname/ directory in order to avoid loading a library for a different target. In the example above, the targetname is gnulinux.

Linking

If you want to link against a library of a built package (because you included one of its headers), you can find that information in the packagename/packagename.pc file. The packagename might be suffixed with -<target> in case it is target specific. The packagename.pc file is generated by the build step and contains all build specific information for this package. You may not modify this file, it will be overwritten. (note: Build systems like ROS get the build information from the manifest.xml file. In Orocos, the build information is generated in a separate file).

When you use the UseOrocos.cmake macros (Orocos Toolchain 2.3.0 or later), linking with dependees will be done automatically for you.

You may add a link instruction using the classical CMake syntax: 

orocos_component( mycomponent ComponentSource.cpp )
target_link_libraries( mycomponent ${YOUR_LIBRARY} )

Using

It is not necessary to define your RTT_COMPONENT_PATH, except if you have installed packages as well.

The component and plugin loaders of RTT will search your ROS_PACKAGE_PATH, and its target subdirectory for components and plugins.

You can then import the package in the deployer application by using: 

import("packagename")
Which will make available all components, typekits and plugins of that package and its depends packages to the current application.

Using installed packages [Autoproj]

This method relies on a 'make install' command in your package.

Layout

All packages are installed in the same root directory that contains all built software, for example /opt/orocos. Orocos packages that deliver built libraries are then installed like this:

# Install dir (the prefix):
/opt/orocos
 
# Headers:
/opt/orocos/include/orocos/gnulinux/packagename/*.hpp
# Component libraries for 'packagename':
/opt/orocos/lib/orocos/gnulinux/packagename/*.so|dll|...
# Plugin libraries for 'packagename':
/opt/orocos/lib/orocos/gnulinux/packagename/plugins/*.so|dll|...
# Type libraries for 'packagename':
/opt/orocos/lib/orocos/gnulinux/packagename/types/*.so|dll|...
# Build information for 'packagename':
/opt/orocos/lib/pkgconfig/packagename-gnulinux.pc

For allowing multi-target installs, the packages will be installed in orocos/targetname/packagename (for example: orocos/xenomai/ocl) in order to avoid loading a library for a different target. In the example above, the targetname is gnulinux.

Linking

If you want to link against a library of an installed package (because you included one of its headers), you can find that information in the lib/pkgconfig/packagename.pc file. Packagenames might be suffixed with -<target> in case they are target specific. When you use the UseOrocos.cmake macros (Orocos Toolchain 2.3.0 or later) or orogen, linking with dependees will be done automatically for you.

You may add a link instruction using the classical CMake syntax: 

orocos_component( mycomponent ComponentSource.cpp )
target_link_libraries( mycomponent -lfoobar )

Using

Point your RTT_COMPONENT_PATH to the lib/orocos directory: 
RTT_COMPONENT_PATH=/opt/orocos/lib/orocos
export RTT_COMPONENT_PATH

The component and plugin loaders of RTT will search this directory, and its target subdirectory for components and plugins. So there is no need to encode the target name in the RTT_COMPONENT_PATH (but you may do so if it is required for some case).

You can then import the package in the deployer application by using: 

import("packagename")
Which will make available all components, typekits and plugins of that package to the current application.