The OROCOS Real-Time Toolkit Installation Guide

Real-Time Toolkit Version 2.6.0

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation, with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of this license can be found at
http://www.fsf.org/copyleft/fdl.html.

1. Setting up your Orocos build environment

We're gradually moving
the contents of the installation manual into the wiki.
Check out the The RTT installation wiki
for completeness.

1.1. Introduction

This sections explains the supported Orocos targets
and the Orocos versioning scheme.

1.1.1. Supported platforms (targets)

Orocos was designed with portability in mind. Currently, we support RTAI/LXRT
(http://www.rtai.org), GNU/Linux
userspace, Xenomai (Xenomai.org), Mac OS X (apple.com) and native Windows
using Microsoft Visual Studio. So,
you can first write your software as a normal Linux/Mac OS X
program, using the framework for testing and debugging
purposes in plain userspace (Linux/Mac OS X) and recompile
later to a real-time target or MS Windows.

1.1.2. The versioning scheme

A particular version is represented by three
numbers separated by dots.For example :

2.2.1 : Release 2, Feature update 2, bug-fix revision
1.

1.1.3. Dependencies on other Libraries

Before you install Orocos, verify that you have the
following software installed on your platform :

Boost.org from version
1.33.0 on has a very efficient (time/space) lock-free
smart pointer implementation which is used by
Orocos. 1.36.0 has boost::intrusive which we require on Windows with MSVS.
1.40.0 has a shared_ptr implementation we require when building Service objects.

Boost C++ Test Library

1.33.0 (During build only)

Boost.org test
library ('unit_test_framework') is required if you build the RTT
from source and ENABLE_TESTS=ON (default). The RTT libraries
don't depend on this library, it is only used for building
our unit tests.

Xerces website
Versions 2.1 until 3.1 are known to work. If not found, an internal
XML parser is used.

ACE & TAO

TAO 1.3 (Optional)

ACE & TAO website
When you start your components in a networked environment,
TAO can be used to set up communication between components.
CORBA is used as a 'background' transport and is hidden for normal users.

Omniorb

4 (Optional)

Omniorb website
Omniorb is more robust and faster than TAO, but has less features.
CORBA is used as a 'background' transport and is hidden for normal users.

All these packages are provided by most Linux distributions. In Mac OS X,
you can install them easily using fink or macports.
Take also a look on the Orocos.org RTT download page
for the latest information.

1.2. Basic Real-Time Toolkit Installation on Windows-like systems

We documented this on the on-line wiki for the various flavours/options
one has on the MS Windows platform:
RTT on MS Windows

1.3. Basic Real-Time Toolkit Installation on Unix-like systems

The RTT uses the CMake
build system for configuring and building the library.

The tool you will need is cmake
Most linux distros have a cmake package, and so do fink/macports in OS X.
In Debian, you can use the official Debian version using

apt-get install cmake

If this does not work for you, you can download cmake from
the CMake homepage.

Next, download the orocos-rtt-2.6.0-src.tar.bz2 package from the
Orocos webpage and extract it using :

tar -xvjf orocos-rtt-2.6.0-src.tar.bz2

This section provides quick installation instructions if you
want to install the RTT on a standard GNU/Linux system. Please check out
Section 3, “Detailed Configuration using 'CMake'” for installation on other OSes and/or if you
want to change the default configuration settings.

2.3. What about main() ?

In case you also want to write an executable that runs
components, your main() function needs to be named
ORO_main().

Some care must be taken in initialising the realtime
environment. First of all, you need to provide a function
int ORO_main(int argc, char** argv)
{...}, defined in <rtt/os/main.h> which contains your program :

If you do not use this function, it is possible that
some (OS dependent) Orocos functionality will not work.

3. Detailed Configuration using 'CMake'

If you have some of the Orocos dependencies installed in
non-standard locations, you have to specify
this using cmake variables before running
the cmake configuration. Specify header locations using
the CMAKE_INCLUDE_PATH variable (e.g. using
bash and fink in Mac OS X, the boost library headers are
installed in /sw/include, so you would specify

export CMAKE_INCLUDE_PATH=/sw/include;/boost/include

For libraries in not default locations, use
the

export CMAKE_LIBRARY_PATH=/sw/libs;/boost/lib

variable.
When your installation directory has a standard layout, you can also
use a single

In order to avoid setting these global exports repeatedly, the RTT
build system reads a file in which you can specify your
build environment. This file is the orocos-rtt.cmake file,
which you obtain by making a copy from orocos-rtt-2.6.0/orocos-rtt.default.cmake
into the same directory. The advantage is that this file lives in the
rtt top source directory, such that it can be re-used across builds.
Using this file is recommended!

3.1. Real-Time Toolkit Build Configuration

The RTT can be configured depending on your target.
For embedded targets, the large scripting infrastructure and
use of exceptions can be left out. When CORBA is available,
an additional library is built which allows components to
communicate over a network.

In order to configure the RTT in detail, you
need to invoke the ccmake command:

cd orocos-rtt-2.6.0/build
ccmake ..

from your build directory. It will offer a configuration
screen. The keys to use are 'arrows'/'enter' to modify a
setting, 'c' to run a configuration check (may be required
multiple times), 'g' to generate the makefiles. If an
additional configuration check is required, the 'g' key can
not be used and you must press again 'c' and examine the output.

3.1.1. RTT with CORBA plugin

In order to enable CORBA, a valid installation of TAO or OMNIORB must be
detected on your system and you must turn the ENABLE_CORBA
option on (using ccmake).
Enabling CORBA does not modify the RTT library and
builds and installs an additional library and headers.

3.2. Configuring the target Operating System

Move to the OROCOS_TARGET, press enter and type
on of the following supported targets (all in lowercase):

gnulinux

macosx

xenomai

lxrt

win32

The xenomai and lxrt targets require the presence of the
LINUX_SOURCE_DIR option since these targets
require Linux headers during the Orocos build. To use the
LibC Kernel headers in
/usr/include/linux, specify
/usr. Inspect the output to find any errors.

Note

From Xenomai version 2.2.0 on, Xenomai configuration
does no longer require the --with-linux option.

3.3. Setting Build Compiler Flags

You can set the compiler flags using the CMAKE_BUILD_TYPE
option. You may edit this field to contain:

Release

Debug

RelWithDebInfo

MinSizeRel

None

In case you choose None, you must set the CMAKE_C_FLAGS, CMAKE_CXX_FLAGS
manually. Consult the CMake manuals for all details.

3.4. Building for RTAI / LXRT

Orocos has been tested with RTAI 3.0, 3.1, 3.2, 3.3, 3.4, 3.5 and 3.6.
The latest version of RTAI is recommended for RTAI users.
You can obtain it from
the RTAI home page.
Read The README.* files in the
rtai directory for detailed
build instructions, as these depend on the RTAI version.

3.4.1. RTAI settings

RTAI comes with documentation for configuration and
installation. During 'make menuconfig', make sure that
you enable the following options (in addition to
options you feel you need for your application) :

After configuring you must run 'make' and 'make install' in your RTAI directory:
makesudo make install

After installation, RTAI can be found in
/usr/realtime. You'll have to specify
this directory in the RTAI_INSTALL_DIR option
during 'ccmake'.

3.4.2. Loading RTAI with LXRT

LXRT is a all-in-one scheduler that works for kernel and userspace.
So if you use this, you can still run kernel programs but have the ability
to run realtime programs in userspace. Orocos provides you the libraries
to build these programs.
Make sure that the following RTAI kernel modules are loaded

rtai_sem

rtai_lxrt

rtai_hal

adeos (depends on RTAI version)

For example, by executing as root:
modprobe rtai_lxrt; modprobe rtai_sem.

3.4.3. Compiling Applications with LXRT

Application which use LXRT as a target need special flags when being
compiled and linked. Especially :

You might also need to add
/usr/realtime/lib to the
/etc/ld.so.conf file and rerun
ldconfig, such that liblxrt.so
can be found. This option is not needed if you
configured RTAI with LXRT-static-inlining.

3.5. Building for Xenomai (version 2.2.0 or newer)

Note

For older Xenomai versions, consult the Xenomai README of that
version.

Xenomai provides a real-time scheduler for Linux applications.
See the Xenomai home
page. Xenomai requires a patch one needs to apply upon
the Linux kernel, using the
scripts/prepare-kernel.sh script. See the
Xenomai installation manual. When applied, one needs to enable
the General Setup -> Interrupt Pipeline
option during Linux kernel configuration and next the
Real-Time Sub-system -> ,
Xenomai and Nucleus. Enable
the Native skin, Semaphores,
Mutexes and Memory Heap. Finally
enable the Posix skin as well.

When the Linux kernel is built, do in the Xenomai directory:
./configure ; make; make install.

You'll have to specify the install directory in the
CMAKE_PATH_PREFIX option during 'cmake'.

3.5.1. Loading Xenomai

The RTT uses the native Xenomai API to address the real-time
scheduler. The Xenomai kernel modules can be found in
/usr/xenomai/modules. Only the
following kernel modules need to be loaded:

xeno_hal.ko

xeno_nucleus.ko

xeno_native.ko

in that order. For example, by executing
as root: insmod xeno_hal.ko; insmod
xeno_nucleus.ko; insmod xeno_native.ko.

3.5.2. Compiling Applications with Xenomai

Application which use Xenomai as a target need special flags
when being compiled and linked. Especially :

You might also need to add
/usr/xenomai/lib to the
/etc/ld.so.conf file and rerun
ldconfig, such that libnative.so
can be found automatically.

3.6. Configuring for CORBA

In case your application benefits from remote access over a
network, the RTT can be used with 'The Ace Orb' (
TAO) or OMNIORB-4. The RTT was tested with TAO 1.3.x,
1.4.x, 1.5x and 1.6.x and OMNIORB 4.1.x. There are two major TAO development lines. One line
is prepared by OCI (Object Computing
Inc.) and the other by the DOC group. You
can find the latest OCI TAO version on OCI's TAO website. The
DOC group's TAO version can be found on the
Real-time CORBA with TAO (The ACE ORB) website.
Debian and Ubuntu users use the latter version when they
install from .deb packages.

If you need commercial support for any TAO release or seek
expert advice on which TAO version or development line to use,
consult the
commercial support website.

If your distribution does not provide the TAO libraries,
or you want to use the OCI version, you need to build
manually. These instructions are for building on
Linux. See the ACE and TAO installation manuals for
building on your platform.

Orocos requires the ACE, TAO and TAO-orbsvcs libraries and
header files to be installed on your workstation. If you
used manual installation, the ACE_ROOT and
TAO_ROOT variables must be set.

3.6.2. Configuring the RTT for TAO or OMNIORB

Orocos RTT defaults to TAO. If you want to use the
OMNIORB implementation, run from your build directory:

cmake .. -DENABLE_CORBA=ON -DCORBA_IMPLEMENTATION=OMNIORB

To specify TAO explicitly (or change back) use:

cmake .. -DENABLE_CORBA=ON -DCORBA_IMPLEMENTATION=TAO

The RTT will first try to detect your location of ACE and
TAO using the ACE_ROOT and TAO_ROOT variables and if these
are not set, using the standard include paths. If TAO or
OMNIORB is found you can enable CORBA support
(ENABLE_CORBA) within CMake.

3.6.3. Application Development with TAO

Once you compile and link your application with Orocos and with the
CORBA functionality enabled, you must provide the correct include
and link flags in your own Makefile if TAO and ACE are not
installed in the default path. Then you must add:

This is again the ACE build directory in case you use OCI's
TAO packages. The first option is not needed if you used
your distribution's TAO installation, in that case,
TAO is in the standard library path.

Important

You also need to add
/path/to/ACE_wrappers/lib to the
/etc/ld.so.conf file and rerun
ldconfig, such that these libraries
can be found. Or you can before you start your application
type

export LD_LIBRARY_PATH=/path/to/ACE_wrappers/lib

.

4. Cross Compiling Orocos

This section lists some points of attention when
cross-compiling Orocos.