<!--Couldn't selectively extract content, Imported Full Body :(-->
<div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div></div><div><h3 class="subtitle"><i><span class="emphasis"><em>Real-Time Toolkit Version 1.4.0</em></span></i></h3></div><div><p class="copyright">Copyright © 2002,2003,2004,2005,2006,2007 Peter Soetens, FMTC</p></div><div><div class="legalnotice"><a id="id2515169"></a><p>
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
<a href="http://www.fsf.org/copyleft/fdl.html" target="_top">http://www.fsf.org/copyleft/fdl.html</a>.
</p></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td align="left">Revision 1.0.0</td><td align="left">27 Okt 2006</td><td align="left">ps</td></tr><tr><td align="left" colspan="3">Simplified build system.</td></tr><tr><td align="left">Revision 1.0.1</td><td align="left">21 Nov 2006</td><td align="left">ps</td></tr><tr><td align="left" colspan="3">Updated build/run/doc dependencies.</td></tr><tr><td align="left">Revision 1.1.0</td><td align="left">13 Apr 2007</td><td align="left">ps</td></tr><tr><td align="left" colspan="3">Rewritten for Orocos 1.2.0.</td></tr><tr><td align="left">Revision 1.2.1</td><td align="left">02 June 2007</td><td align="left">ps</td></tr><tr><td align="left" colspan="3">Minor clarifications.</td></tr><tr><td align="left">Revision 1.4.0</td><td align="left">22 Nov 2007</td><td align="left">ps</td></tr><tr><td align="left" colspan="3">Changes in the library name (-target) and .pc files</td></tr></table></div></div><div><div class="abstract"><p class="title"><b>Abstract</b></p><p>
This document explains how the
Real-Time Toolkit of <a href="http://www.orocos.org" target="_top"><acronym class="acronym">Orocos</acronym></a>,
the <span class="emphasis"><em>Open RObot COntrol Software</em></span> project
must be installed and configured.
</p></div></div></div><hr></hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2515186">1. Setting up your first <acronym class="acronym">Orocos</acronym> source tree </a></span></dt><dd><dl><dt><span class="section"><a href="#setup_intro">1.1. Introduction</a></span></dt><dt><span class="section"><a href="#id2515544">1.2. Basic Real-Time Toolkit Installation</a></span></dt><dt><span class="section"><a href="#id2513696">1.3. Installing an Orocos Build</a></span></dt></dl></dd><dt><span class="section"><a href="#install-configure">2. Detailed Configuration using 'CMake'</a></span></dt><dd><dl><dt><span class="section"><a href="#id2513771">2.1. Configuring the target Operating System</a></span></dt><dt><span class="section"><a href="#install-flags">2.2. Setting Build Compiler Flags</a></span></dt><dt><span class="section"><a href="#general_setup_rtai">2.3. Building for RTAI / LXRT</a></span></dt><dt><span class="section"><a href="#general_setup_xeno">2.4. Building for Xenomai (version 2.2.0 or newer)</a></span></dt><dt><span class="section"><a href="#install-config-corba">2.5. Configuring for CORBA</a></span></dt></dl></dd><dt><span class="section"><a href="#started">3. Getting Started with the Code</a></span></dt><dd><dl><dt><span class="section"><a href="#id2559339">3.1. A quick test</a></span></dt><dt><span class="section"><a href="#id2559366">3.2. What about main() ?</a></span></dt><dt><span class="section"><a href="#id2559580">3.3. Header Files Overview</a></span></dt></dl></dd><dt><span class="section"><a href="#cross-compile">4. Cross Compiling Orocos</a></span></dt></dl></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2515186"></a>1.  Setting up your first <acronym class="acronym">Orocos</acronym> source tree </h2></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="setup_intro"></a>1.1. Introduction</h3></div></div></div><p>
This sections explains the supported Orocos targets
and the Orocos versioning scheme.
</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2515311"></a>1.1.1. Supported platforms (targets)</h4></div></div></div><p>
<acronym class="acronym">Orocos</acronym> was designed with portability in mind. Currently, we support RTAI/LXRT
(<a href="http://www.rtai.org" target="_top">http://www.rtai.org</a>), GNU/Linux
userspace, Xenomai (<a href="http://www.xenomai.org" target="_top">Xenomai.org</a>). So,
you can first write your software as a normal Linux program, using the framework
for testing and debugging purposes in plain userspace Linux and recompile
later to another real-time target.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2515342"></a>1.1.2. The versioning scheme</h4></div></div></div><p>
<acronym class="acronym">Orocos</acronym> uses the even/stable uneven/unstable
version numbering scheme, just as the Linux kernel.
A particular version is represented by three
numbers separated by dots. An <span class="emphasis"><em>even</em></span>
middle number indicates a <span class="emphasis"><em>stable</em></span>
version. For example :
</p><div class="itemizedlist"><ul type="disc"><li><p>1.1.4 : Release 1, unstable (1), revision
-
- .</p></li><li><p>1.2.1 : Release 1, stable (2), revision
- .</p></li></ul></div><p> This numbering allows to develop and release
two kinds of versions, where the unstable version is mainly
for testing new features and designs and the stable version
is for users wanting to run a reliable system.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2515385"></a>1.1.3. Dependencies on other Libraries</h4></div></div></div><p>Before you install Orocos, verify that you have the
following software installed on your platform : </p><div class="table"><a id="id2515396"></a><p class="title"><b>Table 1. Build Requirements</b></p><div class="table-contents"><table summary="Build Requirements" border="1"><colgroup><col></col><col></col><col></col></colgroup><thead><tr><th>Program / Library</th><th><span class="emphasis"><em>Minimum</em></span> Version</th><th>Description</th></tr></thead><tbody><tr><td>Boost C++ Libraries</td><td>0.32.0 (0.33.0 or newer Recommended!)</td><td><a href="http://www.boost.org" target="_top">Boost.org</a> Version
-
- .33.0 has a very efficient (time/space) lock-free
smart pointer implementation which is used by
Orocos.</td></tr><tr><td>GNU gcc / g++ Compilers</td><td>3.3.0</td><td><a href="http://gcc.gnu.org" target="_top">gcc.gnu.org</a>
Orocos builds with the GCC 4.x series as well.</td></tr><tr><td>Xerces C++ Parser</td><td>2.1 (Optional)</td><td><a href="http://xml.apache.org/xerces-c/" target="_top">Xerces website</a>
Versions 2.1 until 2.6 are known to work. If not found, an internal
XML parser is used.</td></tr><tr><td>ACE & TAO</td><td>TAO 1.3 (Optional)</td><td><a href="http://www.cs.wustl.edu/~schmidt/" target="_top">ACE & TAO website</a>
When you start your components in a networked environment,
TAO can be used to set up communication between components.
</td></tr><tr><td>CppUnit Library</td><td>1.9.6 (Optional)</td><td><a href="http://cppunit.sourceforge.net/cgi-bin/moin.cgi" target="_top">CppUnit website.</a>
Only needed if you want to run the Orocos tests.
</td></tr></tbody></table></div></div><br class="table-break"></br><p>
All these packages are provided by most Linux distributions.
Take also a look on the Orocos.org download page for
the latest information.
</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2515544"></a>1.2. Basic Real-Time Toolkit Installation</h3></div></div></div><p>
The RTT uses the <a href="http://www.cmake.org" target="_top">CMake</a>
build system for configuring and building the library.
</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2515560"></a>1.2.1. Orocos Build and Configuration Tools </h4></div></div></div><p>
The tool you will need is <span><strong class="command">cmake</strong></span>
In Debian, you can use the official Debian version using
</p><pre class="screen"> apt-get install cmake</pre><p>
If this does not work for you, you can download cmake from
the CMake homepage.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2513359"></a>1.2.2. Quick Installation Instructions</h4></div></div></div><p>
Download the <code class="filename">orocos-rtt-1.4.0-src.tar.bz2</code> package from the
Orocos webpage.
</p><p>
Extract it using :
</p><pre class="screen"><span><strong class="command"> tar -xvjf orocos-rtt-1.4.0-src.tar.bz2</strong></span></pre><p>
Then proceed as in:
</p><pre class="screen"><span><strong class="command">
mkdir orocos-rtt-1.4.0/build
cd orocos-rtt-1.4.0/build
../configure --with-<target> --prefix=/usr/local--with-linux=/usr/src/linux
make
make check
make install</strong></span> </pre><p>
</p><p>
Where
</p><div class="itemizedlist"><ul type="disc"><li><p>
<target> is one of listed in <span><strong class="command">../configure --help</strong></span>.
( currently 'gnulinux', 'lxrt' or 'xenomai' ). When none is specified,
'gnulinux' is used.</p></li><li><p><code class="option">--prefix</code> specifies where
to install the RTT.</p></li><li><p><code class="option">--with-linux</code> is required for RTAI/LXRT
and older Xenomai version (<2.2.0). It points to
the source location of the RTAI/Xenomai patched Linux kernel.</p></li></ul></div><p>
See <span><strong class="command">configure --help</strong></span> for a full list of options.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="Note" src="../../../../../stable/documentation/rtt/v1.4.x/doc-xml/images/icons/note.png"></img></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>
The <span><strong class="command">configure</strong></span> script is a wrapper
around the 'cmake' command and must be rerun after you
installed missing libraries (like Boost, ...) before you
can build the RTT.
</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2513474"></a>1.2.3. Real-Time Toolkit Configuration</h4></div></div></div><p>
The RTT can be configured depending on you 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.
</p><p>
In order to configure the RTT in detail, you
need to invoke the <span><strong class="command">ccmake</strong></span> command:
</p><pre class="screen"><span><strong class="command">
cd orocos-rtt-1.4.0/build
cmake ..</strong></span> </pre><p>
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.
</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a id="id2513519"></a>RTT with CORBA plugin</h5></div></div></div><p>
In order to enable CORBA a valid installation of TAO must be
detected on your system and you must turn the <code class="option">ENABLE_CORBA</code>
option on (using ccmake).
Enabling CORBA does not modify the RTT library, but
builds and installs an additional library and headers.
</p><p>
Alternatively, when you use the configure wrapper, you
can specify:
</p><pre class="screen"> ../configure --enable-corba</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a id="id2513548"></a>Embedded RTT flavour</h5></div></div></div><p>
In order to run Orocos applications on embedded systems,
one can turn the <code class="option">OS_EMBEDDED</code> option on.
Next press 'c' again and additional options will be
presented which allow you to select what part of the RTT
is used. By default, the <code class="option">OS_EMBEDDED</code>
option already disables some 'fat' features. One can also
choose to build the RTT as a static library
(<code class="option">BUILD_STATIC</code>).
</p><p>
Alternatively, when you use the configure wrapper, you
can specify:
</p><pre class="screen"> ../configure --embedded</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2513587"></a>1.2.4. Build results</h4></div></div></div><p>
The <span><strong class="command">make</strong></span> command will have created a
<code class="filename">liborocos-rtt-<target>.so</code> library, and if
CORBA is enabled a <code class="filename">liborocos-rtt-corba-<target>.so</code>
library.
</p><p>
The <span><strong class="command">make docapi</strong></span> and
<span><strong class="command">make docpdf dochtml</strong></span> (both in 'build') commands build
API documentation and PDF/HTML documentation in the build/doc directory.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2513635"></a>1.2.5. Building <acronym class="acronym">Orocos</acronym> for multiple targets</h4></div></div></div><p>
When you want to build for another target, create a new
build-<target> directory and simply re-invoke
<span><strong class="command">../configure --with-<target></strong></span> from
that build directory.
</p><p>
If this step fails, it means that you have not everything installed
which is needed for a basic <acronym class="acronym">Orocos</acronym> build. Most users don't have the
Boost library (<code class="filename">libboost-dev</code> or
<code class="filename">libboost-devel</code>) installed. Install this
package from the binary or source package repository of your Linux
distribution, or download and install it from the <a href="http://www.boost.org" target="_top">Boost project.</a> As soon as the
configure step succeeds, all the rest will succeed too. Use the
mailinglist at <code class="email"><<a href="orocos-dev [..] ">orocos-dev [..] </a>></code> for
support questions.
</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2513696"></a>1.3. Installing an Orocos Build</h3></div></div></div><p>
Orocos can optionally (<span class="emphasis"><em> but recommended</em></span>)
be installed on your system with </p><pre class="screen"> make install</pre><p>
The default directory is
<code class="filename">/usr/local</code>, but can be changed
with the <code class="option">--with-prefix</code> option : </p><pre class="screen">
../configure --with-prefix=/opt/other/</pre><p>
If you choose not to install Orocos, you can find the build's result
in the <code class="filename">build/src</code> directory.
</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="install-configure"></a>2. Detailed Configuration using 'CMake'</h2></div></div></div><p>
In order to start cmake configuration, in your build
directory, run <span><strong class="command">ccmake ..</strong></span> . Press 'c' (from
'c'onfigure), watch the output, press 'e' (from 'e'xit) and
modify the new options. Repeat these steps until no errors
are reported and the 'g' (from 'g'enerate) key can be pressed.
This causes the makefiles to be generated which allow the
library to be built.
</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2513771"></a>2.1. Configuring the target Operating System</h3></div></div></div><p>
Move to the <code class="option">OROCOS_TARGET</code>, press enter and type
on of the following supported targets (all in lowercase):
</p><div class="itemizedlist"><ul type="disc"><li><p>gnulinux</p></li><li><p>xenomai</p></li><li><p>lxrt</p></li></ul></div><p>
The xenomai and lxrt targets require the presence of the
<code class="option">LINUX_SOURCE_DIR</code> option since these targets
require Linux headers during the Orocos build. To use the
LibC Kernel headers in
<code class="filename">/usr/include/linux</code>, specify
<code class="option">/usr</code>. Inspect the output to find any errors.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="Note" src="../../../../../stable/documentation/rtt/v1.4.x/doc-xml/images/icons/note.png"></img></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>From Xenomai version 2.2.0 on, Xenomai configuration
does no longer require the --with-linux option.</p></td></tr></table></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="install-flags"></a>2.2. Setting Build Compiler Flags</h3></div></div></div><p>
You can set the compiler flags using the <code class="option">CMAKE_BUILD_TYPE</code>
option. You may edit this field to contain:
</p><div class="itemizedlist"><ul type="disc"><li><p>RTT (default)</p></li><li><p>Release</p></li><li><p>Debug</p></li><li><p>RelWithDebInfo</p></li></ul></div><p>
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="general_setup_rtai"></a>2.3. Building for RTAI / LXRT</h3></div></div></div><p>
Read first the 'Getting Started' section from <a href="http://people.mech.kuleuven.be/~psoetens/portingtolxrt.html" target="_top">this
page</a> if you are not familiar with RTAI installation
</p><p>
Orocos has been tested with RTAI 3.0, 3.1, 3.2, 3.3, 3.4 and 3.5.
You can obtain it from
<a href="http://www.aero.polimi.it/projects/rtai/" target="_top">
the RTAI home page</a>.
Read The README.* files in the
<code class="filename">rtai</code> directory for detailed
build instructions, as these depend on the RTAI version.
</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2558657"></a>2.3.1.  RTAI settings </h4></div></div></div><p>
RTAI comes with documentation for configuration and
installation. During 'make menuconfig', make sure that
you enable the following options (<span class="emphasis"><em>in addition to
options you feel you need for your application</em></span>) :
</p><div class="itemizedlist"><ul type="disc"><li><p>General -> 'Enable extended configuration mode'</p></li><li><p>Core System -> Native RTAI schedulers >
Scheduler options -> 'Number of LXRT slots' ('1000') </p></li><li><p>Machine -> 'Enable FPU support'</p></li><li><p>Core System -> Native RTAI schedulers >
IPC support -> Semaphores, Fifos, Bits (or Events) and Mailboxes</p></li><li><p>Add-ons -> 'Comedi Support over LXRT' (if you intend to use the
Orocos Comedi Drivers)</p></li><li><p>Core System -> Native RTAI schedulers >
'LXRT scheduler (kernel and user-space tasks)'</p></li></ul></div><p>
After configuring you must run 'make' and 'make install' in your RTAI directory:
<span><strong class="command">make</strong></span>
<span><strong class="command">sudo make install</strong></span>
</p><p>
After installation, RTAI can be found in
<code class="filename">/usr/realtime</code>. You'll have to specify
this directory in the <code class="option">RTAI_INSTALL_DIR</code> option
during 'ccmake'.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2558760"></a>2.3.2. Loading RTAI with LXRT</h4></div></div></div><p>
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
</p><div class="itemizedlist"><ul type="disc"><li><p>rtai_sem</p></li><li><p>rtai_lxrt</p></li><li><p>rtai_hal</p></li><li><p>adeos (depends on RTAI version)</p></li></ul></div><p>
For example, by executing as root:
<span><strong class="command">modprobe rtai_lxrt; modprobe rtai_sem</strong></span>.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2558805"></a>2.3.3. Compiling Applications with LXRT</h4></div></div></div><p>
Application which use LXRT as a target need special flags when being
compiled and linked. Especially :
</p><div class="itemizedlist"><ul type="disc"><li><p>
Compiling : <code class="option">-I/usr/realtime/include</code>
</p><p>
This is the RTAI headers installation directory.
</p></li><li><p>
Linking : <code class="option">-L/usr/realtime/lib -llxrt</code> for dynamic (.so) linking OR add
<code class="option"> /usr/realtime/liblxrt.a </code> for static (.a) linking.
</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="Important" src="../../../../../stable/documentation/rtt/v1.4.x/doc-xml/images/icons/important.png"></img></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>
You might also need to add
<code class="filename">/usr/realtime/lib</code> to the
<code class="filename">/etc/ld.so.conf</code> file and rerun
<span><strong class="command">ldconfig</strong></span>, such that liblxrt.so
can be found. This option is not needed if you
configured RTAI with LXRT-static-inlining.
</p></td></tr></table></div></li></ul></div><p>
</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="general_setup_xeno"></a>2.4. Building for Xenomai (version 2.2.0 or newer)</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="Note" src="../../../../../stable/documentation/rtt/v1.4.x/doc-xml/images/icons/note.png"></img></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>
For older Xenomai versions, consult the Xenomai README of that
version.</p></td></tr></table></div><p>
Xenomai provides a real-time scheduler for Linux applications.
See <a href="http://www.xenomai.org" target="_top"> the Xenomai home
page</a>. Xenomai requires a patch one needs to apply upon
the Linux kernel, using the
<span><strong class="command">scripts/prepare-kernel.sh</strong></span> script. See the
Xenomai installation manual. When applied, one needs to enable
the <code class="option">General Setup -> Interrupt Pipeline</code>
option during Linux kernel configuration and next the
<code class="option">Real-Time Sub-system -> </code>,
<code class="option">Xenomai</code> and <code class="option">Nucleus</code>. Enable
the <code class="option">Native</code> skin, <code class="option">Semaphores</code>,
<code class="option">Mutexes</code> and <code class="option">Memory Heap</code>. Finally
enable the <code class="option">Posix</code> skin as well.
</p><p>
When the Linux kernel is built, do in the Xenomai directory:
<span><strong class="command">./configure ; make; make install</strong></span>.
</p><p>
You'll have to specify the install directory in the
<code class="option">XENOMAI_INSTALL_DIR</code> option during 'ccmake'.
</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2558972"></a>2.4.1. Loading Xenomai</h4></div></div></div><p>
The RTT uses the native Xenomai API to address the real-time
scheduler. The Xenomai kernel modules can be found in
<code class="filename">/usr/xenomai/modules</code>. Only the
following kernel modules need to be loaded:
</p><div class="itemizedlist"><ul type="disc"><li><p>xeno_hal.ko</p></li><li><p>xeno_nucleus.ko</p></li><li><p>xeno_native.ko</p></li></ul></div><p>
in that order. For example, by executing
as root: <span><strong class="command">insmod xeno_hal.ko; insmod
xeno_nucleus.ko; insmod xeno_native.ko</strong></span>.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2559017"></a>2.4.2. Compiling Applications with Xenomai</h4></div></div></div><p>
Application which use Xenomai as a target need special flags
when being compiled and linked. Especially :
</p><div class="itemizedlist"><ul type="disc"><li><p>
Compiling : <code class="option">-I/usr/xenomai/include</code>
</p><p>
This is the Xenomai headers installation directory.
</p></li><li><p>
Linking : <code class="option">-L/usr/xenomai/lib
-lnative</code> for dynamic (.so) linking OR add
<code class="option"> /usr/xenomai/libnative.a </code> for
static (.a) linking.
</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="Important" src="../../../../../stable/documentation/rtt/v1.4.x/doc-xml/images/icons/important.png"></img></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>
You might also need to add
<code class="filename">/usr/xenomai/lib</code> to the
<code class="filename">/etc/ld.so.conf</code> file and rerun
<span><strong class="command">ldconfig</strong></span>, such that libnative.so
can be found automatically.
</p></td></tr></table></div></li></ul></div><p>
</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="install-config-corba"></a>2.5. Configuring for CORBA</h3></div></div></div><p>
In case your application benefits from remote access over a
network, the RTT can be used with 'The Ace Orb' or
<span class="emphasis"><em>TAO</em></span> version prepared by OCI (Object
Computing Inc.). You can find the latest TAO version on <a href="http://www.theaceorb.com" target="_top">OCI's TAO website</a>. The
RTT was tested with OCI's TAO 1.3 and 1.4. The OCI version is
prefered above the versions provided by the DOC group on the
<a href="http://www.cs.wustl.edu/~schmidt/TAO.html" target="_top">
Real-time CORBA with TAO (The ACE ORB) website</a>.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="Note" src="../../../../../stable/documentation/rtt/v1.4.x/doc-xml/images/icons/note.png"></img></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>
Orocos requires the ACE, TAO and TAO-orbsvcs libraries and
header files to be installed on your workstation and
<span class="emphasis"><em>that the ACE_ROOT and TAO_ROOT variables are set.</em></span>
</p></td></tr></table></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2559139"></a>2.5.1. TAO installation (Optional)</h4></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="Note" src="../../../../../stable/documentation/rtt/v1.4.x/doc-xml/images/icons/note.png"></img></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>
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.
</p></td></tr></table></div><p>
You need to make an ACE/TAO build on your workstation.
Download the package here: <a href="http://www.theaceorb.com/downloads/1.4a/index.html" target="_top">OCI
Download</a>. Unpack the tar-ball, and enter
<code class="filename">ACE_wrappers</code>. Then do:
<span><strong class="command"> export ACE_ROOT=TeX Embedding failed!(pwd)/TAO
</strong></span> Configure ACE for Linux by doing:
<span><strong class="command"> ln -s ace/config-linux.h ace/config.h
ln -s include/makeinclude/platform_linux.GNU include/makeinclude/platform_macros.GNU
</strong></span> Finally, type:
<span><strong class="command"> make
cd TAO
make
cd orbsvcs
make
</strong></span> This finishes your TAO build.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2559198"></a>2.5.2. Configuring the RTT for TAO</h4></div></div></div><p>
Orocos will first try to detect your location of ACE and TAO
using the ACE_ROOT and TAO_ROOT variables. If these are set, you can enable
CORBA support (<code class="option">ENABLE_CORBA</code>) within CMake.
</p><p>
Alternatively, when you use the configure wrapper, you
can specify:
</p><pre class="screen"> ../configure --enable-corba</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2559226"></a>2.5.3. Application Development with TAO</h4></div></div></div><p>
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:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Compiling : <code class="option">-I/path/to/ACE_wrappers -I/path/to/ACE_wrappers/TAO -I/path/to/ACE_wrappers/TAO/orbsvcs</code>
</p><p>
This is the ACE build directory in case you use OCI's
TAO packages. This option is not needed if you used
your distribution's TAO installation, in that case,
TAO is in the standard include path.
</p></li><li><p>
Linking : <code class="option">-L/path/to/ACE_wrappers/lib -lTAO -lACE -lTAO_IDL_BE -lTAO_PortableServer -lTAO_CosNaming</code>
</p><p>
This is again the ACE build directory in case you use OCI's
TAO packages. The <span class="emphasis"><em>first</em></span> option is not needed if you used
your distribution's TAO installation, in that case,
TAO is in the standard library path.
</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="Important" src="../../../../../stable/documentation/rtt/v1.4.x/doc-xml/images/icons/important.png"></img></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>
You also need to add
<code class="filename">/path/to/ACE_wrappers/lib</code> to the
<code class="filename">/etc/ld.so.conf</code> file and rerun
<span><strong class="command">ldconfig</strong></span>, such that these libraries
can be found. Or you can before you start your application
type </p><pre class="screen">export LD_LIBRARY_PATH=/path/to/ACE_wrappers/lib</pre><p>.
</p></td></tr></table></div></li></ul></div><p>
</p></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="started"></a>3. Getting Started with the Code</h2></div></div></div><p>
This Section provides a short overview of how to proceed next using the
<acronym class="acronym">Orocos</acronym> Real-Time Toolkit.
</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2559339"></a>3.1. A quick test</h3></div></div></div><p>
You can issue a <span><strong class="command">make check</strong></span> in the Orocos
build directory, but this stresses your system heavily. make
check for the gnulinux target should successfuly complete.
</p><p>
To quickly test an <acronym class="acronym">Orocos</acronym> application, you can download the examples
from the webpage.
</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2559366"></a>3.2. What about main() ?</h3></div></div></div><p>
The first question asked by many users is : How do I write a
test program to see how it works?
</p><p>
Some care must be taken in initialising the realtime
environment. First of all, you need to provide a function
<code class="function">int ORO_main(int argc, char** argv)
{...}</code>, defined in <rtt/os/main.h> which contains your program :
</p><pre class="programlisting"> #include <rtt/os/main.h>
int ORO_main(int argc, char** argv)
{
// Your code, do not use 'exit()', use 'return' to
// allow Orocos to cleanup system resources.
} </pre><p>
If you do not use this function, it is possible that
some (OS dependent) Orocos functionality will not work.
</p><div class="example"><a id="id2559409"></a><p class="title"><b>Example 1. A Makefile for an Orocos Application</b></p><div class="example-contents"><p>
You can then simply compile your program with a Makefile
resembling this one :
</p><pre class="programlisting"> OROPATH=/usr/local
# Use 'gnulinux' target:
CXXFLAGS=`PKG_CONFIG_PATH=TeX Embedding failed!{OROPATH}/lib/pkgconfig pkg-config orocos-rtt-gnulinux --libs`
all: myprogram.cpp
g++ myprogram.cpp TeX Embedding failed!{LDFLAGS} -o myprogram </pre><p>
The flags must be extended with compile and link options
for your particular application.
</p><p>
</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="Important" src="../../../../../stable/documentation/rtt/v1.4.x/doc-xml/images/icons/important.png"></img></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>The <code class="option">LDFLAGS</code> option must be placed after
the <code class="filename">.cpp</code> or <code class="filename">.o</code>
files in the gcc command.</p></td></tr></table></div><p>
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="Note" src="../../../../../stable/documentation/rtt/v1.4.x/doc-xml/images/icons/note.png"></img></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Make sure you have read <a href="#install-configure" title="2. Detailed Configuration using 'CMake'">Section 2, “Detailed Configuration using 'CMake'”</a>
for your target if you application has compilation or link errors
( for example when using LXRT ).
</p></td></tr></table></div><p>
</p></div></div><br class="example-break"></br></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2559580"></a>3.3. Header Files Overview</h3></div></div></div><p>
</p><div class="table"><a id="id2559588"></a><p class="title"><b>Table 2. Header Files</b></p><div class="table-contents"><table summary="Header Files" border="1"><colgroup><col></col><col></col></colgroup><thead><tr><th>Header</th><th>Summary</th></tr></thead><tbody><tr><td>rtt/*.hpp</td><td>The `Real-Time Toolkit' directory contains the
headers which describe the public API.
</td></tr><tr><td>rtt/os/*.h, rtt/os/*.hpp</td><td>Not intended for normal users. The os headers
describe a limited set of OS primitives, like locking
a mutex or creating a thread. Read the OS manual
carefully before using these headers, they are mostly
used internally by the RTT.
</td></tr><tr><td>rtt/dev/*.hpp</td><td>C++ Headers for accessing hardware interfaces.
</td></tr><tr><td>rtt/corba/*.hpp</td><td>C++ Headers for CORBA support.
</td></tr><tr><td>rtt/scripting/*.hpp</td><td>C++ Headers for real-time scripting. Do not include these
directly as they are mainly for internal use.
</td></tr><tr><td>rtt/marsh/*.hpp</td><td>C++ Headers for XML configuration and converting
data to text and vice versa.
</td></tr><tr><td>rtt/dlib/*.hpp</td><td>C++ Headers for the experimental Distribution
Library which allows embedded systems to use some
RTT primitives over a network. This directory does not
contain such a library but only interface headers.
</td></tr><tr><td>rtt/impl/*.hpp</td><td>C++ Headers for internal use.
</td></tr></tbody></table></div></div><p><br class="table-break"></br>
</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="cross-compile"></a>4. Cross Compiling Orocos</h2></div></div></div><p>
This section lists some points of attention when
cross-compiling Orocos.
</p><p>
Run plain "cmake" or "ccmake" with the following options:
</p><pre class="screen"><span><strong class="command">
CC=cross-gcc CXX=cross-g++ LD=cross-ld cmake .. -DCROSS_COMPILE=cross-</strong></span></pre><p>
and substitute the 'cross-' prefix with your target tripplet,
for example with 'powerpc-linux-gnu-'. This works roughly when
running on Linux stations, but is not the official 'CMake' approach.
</p><p>
For having native cross compilation support, you must upgrade
to CMake 2.6.0 or later and follow the instructions on the
<a href="http://www.cmake.org/Wiki/CMake_Cross_Compiling" target="_top">
CMake Cross Compiling page</a>.
</p></div></div>
