Robotics Systems Types

h1. Structure Proposal

h2. Requirements

In general, the following requirements try to enforce the general *reusability* of data types.

* *Visibility*: Data definitions must be easily visible when searching for them to foster reuse. This includes:

** Folder browsing

** Code completion

* *Structuredness*: A structured view on the data is required as an orthogonal perspective to the general visibility in order to find functionally coherent groups of data definitions.

* *Stability*: A core set of data definitions must be kept stable as much as possible in order to shield depending software from frequent changes.

* *Extendability*: New data type definitions are constantly required. Adding them to the repository must have a low barrier to motivate data type sharing.

* *Addressability*: A certain revision of a data type must be uniquely addressable and accessible in order to conserve system states.

* *Practicability*: Data type definitions must be usable in an efficient manner in all target languages. This includes also the use of languages where IDL definitions are parsed at runtime and not compiled statically.

h2. Proposed Solution

h3. Packaging

* RST will be split into two separate libraries. Both libraries will be built by the same build-system and use the _same_ naming and structure conventions.

** _RST_: stable data type definitions. Types in this library must not use types from beta.

** _RST-beta_: new data type definitions which may be modified constantly. Beta-types may include types from stable.

* Using the beta library will require explicit requests from the application developer, e.g. by using a separate pkg-config file. Also, e.g. for C++, the headers will be separated into different subdirectories in a way that using the stable library will not make the headers of the beta library automatically available to the compiler.

* Libraries will be built for C++, Java and Python.

h3. Data Type Integration Procedure

* New data types can be added by every developer to the beta library using the specified style guide.

* The RST team will merge the data types from beta to stable from time to time. During this process modifications to the data are explicitly allowed in order to meet the style and quality requirements of the stable library.

* We will shortly integrate fundamental data types instable inspired by ROS, Orocos etc.

* Modifications to existing data types will make use of protobuf's backwards compatibility features whenever possible.

h3. Structure

* The svn will contain a single tree for organizing the data definitions. This tree (i.e. the definition of appropriate categories) will be inspired by the data layout of ROS, Orocos and other robotics middlewares.

* Folders in the match the package provided in the IDL files.

* A Redmine plugin will be created to browse the list of data types, e.g. in a flat list for easy search.

h3. Versioning

* No manual versioning will be used. Especially, no versions will be synchronized with RSB releases. Instead, svn revisions will be the only means of addressing specific versions. svn revisions will be integrated into the library for using them in the code or with the C++ preprocessor.

h3. Style Guide

* A style guide will be defined (or the current one will be improved) to cover more aspects, e.g. like the canonical format for the java_outer_classname option.

* Even if some contents of the files can be defined canonically, we will not generate them using the build system.

* The style guide will explicitly define that data type names do not contain artifacts of their current application. E.g. if a something is used as an event, the data type name must not contain the an event suffix or prefix.

* All data types will have a common package, i.e. rst.

h2. Addressed Requirements

h3. Visibility

* The redmine plugin as well as the common namespace for all data types will make them visible through search as well as code completion.

* The hierarchical structure will foster the visibility coherent groups of data types.

* The possibility to integrate beta types as soon as possible make them visible in an early stage using the same mechanisms like for the stable library. This will foster exchange with other developers on these types.

h3. Structuredness

* The proposed hierarchical structure provides a simple means to group messages and prevent the pollution of a single namespace.

h3. Stability

* The provided core set of data types will form a common basis for all additions.

* The stable library specifies policies for stability of data types definitions with backwards compatibility whenever possible.

* By using the same namespaces for the beta library, data types which will be moved to the stable library from beta will not cause changing includes etc. as long as their initial position in the RST structure was well-chosen.

h3. Extendability

* By giving (nearly) public write access to the beta library, the barrier for adding or modifying types is quite low, especially compared to a formal review process already in this stage.

* The common build system for RST automatically maintains the addition of new files without manual work.

h3. Addressability

* Formal releases were rejected to foster constant change for the beta library and the simultaneous build process of both library parts.

* SVN revisions already provide a formal way of addressing either the whole library or certain types. Code integration of this versions will make this information easily accessible.

h3. Practicability

* Providing compiled libraries of RST decreases the required work in the own build system for generating classes from the IDL files.

* For C++ and Java, providing a common library prevents subtle errors which occur if one IDL file is compiled multiple times and linked into one binary.

h2. Identified Drawbacks

* The hierarchical structure does not provide a means of creating multiple overlapping organizational structures like e.g. tags would. However, it is the only feasible structure that is visible without processing the files by some kind of script or build system. A solution with symlinks would cause a lot of technical and organization problems. Hence, it was rejected.

* Python naming of modules

h2. Open Issues

* Control aspects over data types (arne), i.e. is a cca folder good or bad?