.. _section-rtiddsgen:

Generating Type Support with rtiddsgen
======================================
    
Why Use rtiddsgen?
------------------

For |me| to publish and subscribe to topics of user-defined types, the types 
have to be defined and programmatically registered with |me|.  A registered type 
is then serialized and deserialized by |me| through a pluggable type interface 
that each type must implement. 
    
Rather than have users manually implement each new type, |me| provides the 
*rtiddsgen* utility for automatically generating type support code.  

IDL Type Definition
-------------------

*rtiddsgen* for |me| accepts types defined in IDL. The HelloWorld examples 
included with |me| use the following HelloWorld.idl::
    
        struct HelloWorld {
            string<128> msg;
        };

For further reference, see :link_external_community_doc_pro_um:`the section on Creating User Data Types with IDL <index.htm#users_manual/Creating_User_Data_Types_with_IDL.htm>` in 
the :link_external_community_doc_pro_um:`RTI Connext DDS Core Libraries User's Manual <index.htm>` (available :link_external_community_doc_pro_um:`here <index.htm#users_manual/Creating_User_Data_Types_with_IDL.htm>` if you have 
Internet access).

Generating Type Support
-----------------------

Before running *rtiddsgen*, some environment variables must be set:

- ``RTIMEHOME`` sets the path of the |me| installation directory
- ``RTIMEARCH`` sets the platform architecture (e.g. i86Linux2.6gcc4.4.5 or i86Win32VS2010)
- ``JREHOME`` sets the path for a Java JRE 
    
Note that a JRE is shipped with |core_pro| on platforms supported for the execution
of rtiddsgen (Linux, Windows, and macOS). It is not necessary to set ``JREHOME``
on these platforms, unless a specific JRE is preferred.

C
. 

Run *rtiddsgen* from the command line to generate C language type-support for a 
UserType.idl (and replace any existing generated files)::

    > cd $rti_connext_micro_root/rtiddsgen/scripts
    > rtiddsgen -micro -language C -replace UserType.idl

C++
...

Run *rtiddsgen* from the command line to generate C++ language type-support for a 
UserType.idl (and replace any existing generated files)::

    > cd $rti_connext_micro_root/rtiddsgen/scripts
    > rtiddsgen -micro -language C++ -replace UserType.idl
    
Notes on Command-Line Options
............................. 

In order to target |me| when generating code with *rtiddsgen*, the ``-micro``
option must be specified on the command line.
    
To list all command-line options specifically supported by *rtiddsgen*
for |me|, enter: ::
    
    > cd $rti_connext_micro_root/rtiddsgen/scripts
    > rtiddsgen -micro -help
    
Existing users might notice that that previously available options, ``-language microC``
and ``-language microC++``, have been replaced by ``-micro -language C`` and
``-micro -language C++``, respectively. It is still possible to specify ``microC`` and
``microC++`` for backwards compatibility, but users are advised to switch to 
using the ``-micro`` command-line option along with other arguments.
    
Generated Type Support Files
............................

*rtiddsgen* will produce the following header and source files for each IDL
file passed to it:
    
- UserType.h and UserType.c(xx) implement creation/intialization and deletion 
  of a single sample and a sequence of samples of the type (or types)
  defined in the IDL description.
      
- UserTypePlugin.h and UserTypePlugin.c(xx) implement the pluggable type interface that
  |me| uses to serialize and deserialize the type.
     
- UserTypeSupport.h and UserTypeSupport.c(xx) define type-specific *DataWriters* 
  and *DataReaders* for user-defined types.

Using custom data-types in |me_h| Applications
----------------------------------------------

A |me| application must first of all include the generated headers. Then 
it must register the type with the *DomainParticipant* before a topic of that
type can be defined. For an example HelloWorld type, the following code registers
the type with the participant and then creates a topic of that type::

       #include "HelloWorldPlugin.h"
       
       /* ... */
   
       retcode = DDS_DomainParticipant_register_type(application->participant,
                                                     "HelloWorld",
                                                     HelloWorldTypePlugin_get());
       if (retcode != DDS_RETCODE_OK)
       {
           /* Log an error */
           goto done;
       }

       application->topic =
           DDS_DomainParticipant_create_topic(application->participant,
                                              "Example HelloWorld",
                                              "HelloWorld",
                                              &DDS_TOPIC_QOS_DEFAULT, NULL,
                                              DDS_STATUS_MASK_NONE);

       if (application->topic == NULL)
       {
           /* Log an error */
           goto done;
       }

See the full HelloWorld examples for further reference.
   
Customizing generated code
--------------------------
   
*rtiddsgen* allows |me| users to select whether they want to generate code
to subscribe to and/or publish a custom data-type.
When generating code for subscriptions, only those parts of code dealing with deserialization
of data and the implementation of a typed *DataReader* endpoint are generated.
Conversely, only those parts of code addressing serialization and the implementation
of a *DataWriter* are considered when generating publishing code.
   
Control over these options is provide by two command-line arguments:

- ``-reader`` generates code for deserializing custom data-types and creating *DataReaders* 
  from them.
- ``-writer`` generates code for serializing custom data-types and creating *DataWriters* 
  from them. 
   
If neither of these two options are supplied to *rtiddsgen*, they will both be considered active and
code for both *DataReaders* and *DataWriters* will be generated. If only one of the two options is 
supplied to *rtiddsgen*, only that one is enabled. If both options are supplied, both are enabled. 


.. _`rtiddsgen_unsupported_features`:

Unsupported Features of rtiddsgen with |me_h|
-------------------------------------------------

|me| supports a subset of the features and options in *rtiddsgen*.  
Use ``rtiddsgen -micro -help`` to see the list of features supported by 
*rtiddsgen* for |me|.