WP1 RTT Cleanup

This work package contains structural clean-ups for the RTT source code, such as CMake build system, portability and making the public interface slimmer and explicit. RTT 2.0 is an ideal mark point for doing such changes. Most of these reorganizations have broad support from the community. This package is put up front because it allows early adopters to switch only at the beginning to the new code structure and that all subsequent packages are executed in the new structure.

Links : (various posts on Orocos mailing lists)

Allocated Work : 15 days


1.1 Partition in name spaces and hide internal classes in subdirectories.

A namespace and directory partitioning will once and for all separate public RTT API from internal headers. This will provide a drastically reduced class count for users, while allowing developers to narrow backwards compatibility to only these classes. This offers also the opportunity to remove classes that are for internal use only but are in fact never used.

Deliverable Title Form
1.1.1 Internal headers are in subdirectories Patch set
1.1.2 Internal classes are in nested namespaces of the RTT namespace Patch set

1.2 Improve CMake build system

Numerous suggestions have been done on the mailing list for improving portability and building Orocos on non standard platforms.

Deliverable Title Form
1.2.1 Standardized on CMake 2.6 Patch set
1.2.2 Use CMake lists instead of strings Patch set
1.2.3 No more use of Linux specific include paths Patch set
1.2.4 Separate finding from using libraries for all RTT dependencies Patch set

1.3 Group user contributed code in rtt/extras.

This directory offers variants of implementations found in the RTT, such as new data type support, specialized activity classes etc. In order not to clutter up the standard RTT API, these contributions are organized in a separate directory. Users are warned that these extras might not be of the same quality as native RTT classes.

Deliverable Title Form
1.3.1 Orocos rtt-extras directory Directory in RTT

1.4 Improve portability

Some GNU/GCC/Linux specific constructs have entered the source code, which makes maintenance on and portability to other platforms a harder task. To structurally support other platforms, the code will be compiled with another compiler (non-gnu) and a build flag ORO_NO_ATOMICS (or similar) is added to exclude all compiler and assembler specific code and replace it with ISO-C/C++ or RTT-FOSI compliant constructs.

Deliverable Title Form
1.4.1 Code compiles on non-gnu compiler Patch set
1.4.2 Code compiles without assembler constructs Patch set

1.5 Default to activity with one thread per component

The idea is to provide each component with a robust default activity object which maps to exactly one thread. This thread can periodically execute or be non periodic. The user can switch between these modes at configuration or run-time.

Deliverable Title Form
1.5.1 Generic Activity class which is by default present in every component. Patch set
1.5.2 Unit test for this class Patch set

1.6 Standardize on Boost Unit Testing Framework

Before the other work packages are started, the RTT must standardize on a unit test framework. Until now, this is the CppUnit framework. The more portable and configurable Boost UTF has been chosen for unit testing of RTT 2.0.

Deliverable Title Form
1.6.1 CppUnit removed and Boost UTF in place Patch set

1.7 Provide CMake macros for applications and components

When users want to build Orocos components or applications, they require flags and settings from the installed RTT and OCL libraries. A CMake macro which gathers these flags for compiling an Orocos component or application is provided. This is inspired on how ROS components are compiled.

Deliverable Title Form
1.7.1 CMake macro CMake macro file
1.7.2 Unit test that tests this macro Patch set

1.8 Allow lock-free policies to be configured

Some RTT classes use hard-coded lock-free algorithms, which may be in the way (due to resource restrictions) for some embedded systems. It should be possible to change the policy to not use a lock-free algorithm in that class (cfr the 'strategy' design pattern'). An example is the use of AtomicQueue in the CommandProcessor.

Deliverable Title Form
1.8.1 Allow to set/override lock-free algorithm policy patch

CMake Rework

This page collects all the data and links used to improve the CMake build system, such that you can find quick links inhere instead of scrolling through the forum.

Thread on Orocos-dev : http://www.orocos.org/node/1073 (in case you like to scroll)

CMake manual on how to use and create Findxyz macros : http://www.vtk.org/Wiki/CMake:How_To_Find_Libraries

List of many alternative modules : http://zi.fi/cmake/Modules/

An alternative solution for users of RTT and OCL is installing the Orocos-RTT-target-config.cmake macros, which serve a similar purpose as the pkgconfig .pc files: they accumulate the flags used to build the library. This may be a solution for Windows systems. Also, CMake suggests that .pc files are only 'suggestive' and that still the standard CMake macros must be used to fully capture and store all information of the dependency you're looking at.

Directories and namespace rework

The orocos/src directory reflects the /usr/include/rtt directory structure, I'll post it here from the user's point of view, so what she finds in the include dir:

Abbrevs: (N)BC: (No) Backwards Compatibility guaranteed between 2.x.0 and 2.y.0. Backwards compatibility is always guaranteed between 2.x.y and 2.x.z. In case of NBC, a class might disappear or change, as long as it is not a base class of a BC qualified class.

Directory Namespace BC/NBC Comments Header File list
rtt/*.hpp RTT BC Public API: maintains BC, a limited set of classes and interfaces. This is the most important list to get right. A header not listed in here goes into one of the subdirectories. Please add/complete/remove. TaskContext.hpp Activity.hpp SequentialActivity.hpp SlaveActivity.hpp DataPort.hpp BufferPort.hpp Method.hpp Command.hpp Event.hpp Property.hpp PropertyBag.hpp Attribute.hpp Time.hpp Timer.hpp Logger.hpp
rtt/plugin/*.hpp RTT::plugin BC All plugin creation and loading stuff. Plugin.hpp
rtt/types/*.hpp RTT::types BC All type system stuff (depends partially on plugin). Everything you (or a tool) need(s) to add your own types to the RTT. Toolkit.hpp ToolkitPlugin.hpp Types.hpp TypeInfo.hpp TypeInfoName.hpp TypeStream.hpp TypeStream-io.hpp VectorComposition.hpp TemplateTypeInfo.hpp Operators.hpp OperatorTypes.hpp BuildType.hpp
rtt/interface/*.hpp RTT::interface BC Most interfaces/base classes used by classes in the RTT namespace. ActionInterface.hpp, ActivityInterface.hpp, OperationInterface.hpp, PortInterface.hpp, RunnableInterface.hpp, BufferInterface.hpp
rtt/internal/*.hpp RTT::internal NBC Supportive classes that don't fit another category but are definately not for users to use directly. ExecutionEngine.hpp CommandProcessor.hpp DataSource*.hpp Command*.hpp Buffer*.hpp Function*.hpp *Factory*.hpp Condition*.hpp Local*.hpp EventC.hpp MethodC.hpp CommandC.hpp
rtt/scripting/*.hpp RTT::scripting NBC Users should not include these directly.
rtt/extras/*.hpp RTT::extras BC Alternative implementations of certain interfaces in the RTT namespace. May contain stuff useful for embedded or other specific use cases.
rtt/dev/*.hpp RTT::dev BC Minimal Device Interface, As-is in RTT 1.x AnalogInInterface.hpp AnalogOutInterface.hpp AxisInterface.hpp DeviceInterface.hpp DigitalInput.hpp DigitalOutput.hpp EncoderInterface.hpp PulseTrainGeneratorInterface.hpp AnalogInput.hpp AnalogOutput.hpp CalibrationInterface.hpp DigitalInInterface.hpp DigitalOutInterface.hpp DriveInterface.hpp HomingInterface.hpp SensorInterface.hpp
rtt/corba/*.hpp RTT::corba BC CORBA transport files. Users include some headers, some not. Should this also have the separation between rtt/corba and rtt/corba/internal ? I would rename the IDL modules to RTT::corbaidl in order to clear out compiler/doxygen confusion. Also note that current 1.x namespace is RTT::Corba.
rtt/property/*.hpp RTT::property BC Formerly 'rtt/marsh'. Marshalling and loading classes for properties. CPFDemarshaller.hpp CPFDTD.hpp CPFMarshaller.hpp
rtt/dlib/*.hpp RTT::dlib BC As-is static distribution library files. They are actually a form of 'extras'. Maybe they belong in there... DLibCommand.hpp
rtt/boost/*.hpp boost ? We'll try to get rid of this in 2.x
rtt/os/*.hpp RTT::OS BC As-is. (Rename to RTT::os ?) Atomic.hpp fosi_internal_interface.hpp MutexLock.hpp rt_list.hpp StartStopManager.hpp threads.hpp CAS.hpp MainThread.hpp oro_allocator.hpp rtconversions.hpp rtstreambufs.hpp Semaphore.hpp Thread.hpp Time.hpp fosi_internal.hpp Mutex.hpp OS.hpp rtctype.hpp rtstreams.hpp ThreadInterface.hpp
rtt/targets/* - BC We need this for allowing to install multiple -dev versions (-gnulinux+-xenomai for example) in the same directory. rtt-target.h <target>

Will go: 'rtt/impl' and 'rtt/boost'.

Open question to be answered: Interfaces like ActivityInterface, PortInterface, RunnableInterface etc. -> Do they go into rtt/, rtt/internal or maybe rtt/interface ?

!!! PLEASE add a LOG MESSAGE when you edit this wiki to motivate your edit !!!