.. _example_generation:

Generating Examples
===================

The RTI *Code Generator* (also referred to as *rtiddsgen*) included with |me| 
can generate DDS example applications with a type definition file as input.

.. note:: 
    
  Before running *rtiddsgen*, you might need to add
  ``rti_connext_dds-<version>/rtiddsgen/scripts`` to your path environment 
  variable folder.

Default example
---------------

To generate an example, run the following command:

.. code-block:: console

    rtiddsgen -example -language <C> <file with type definition>

This generates an example using the default example template, which uses
the Dynamic Participant Static Endpoint (DPSE) discovery plugin and UDP
communication.

*rtiddsgen* accepts the following options:

-  ``-example``: Generates type files, example files, and CMakelists files.
-  ``-language <C>``: Generates C code.

The generated example can then be compiled using `CMake <https://cmake.org/>`_ and
the ``CMakelists.txt`` file generated by *Code Generator*. *Code Generator* 
also creates a ``README.txt`` file with a description of the example and 
instructions for how to compile and run it.

Custom example
--------------

*Code Generator* can also generate examples using custom templates with 
the option ``-exampleTemplate <templateName>``.

To generate an example using a custom template instead of the default one,
run the following command:

.. code-block:: console

    rtiddsgen -example -exampleTemplate <template name> -language <C> <file with type definition>

To see the list of the available templates for each language, run the 
following command:

.. code-block:: console

    rtiddsgen -showTemplates

As an example, the following command will generate an example in the C language, 
using the ``zerocopy`` custom template instead of the default template:

.. code-block:: console

    rtiddsgen -example -exampleTemplate zerocopy -language C <file with type definition>


Descriptions of generated examples
----------------------------------

Each example consists of a publication and subscription pair to send and receive
the type specified by the user. When compiled, the example creates two 
applications: one to send samples (a publisher) and another to receive samples
(a subscriber).

- **default example (no template specified)**
    
  Discovery of endpoints is done with the static-endpoint discovery (DPSE). 
  Only the UDP and INTRA transports are enabled.
  The subscriber application creates a *DataReader*, which uses a listener to
  receive notifications about new samples and matched publishers. These
  notifications are received in the middleware thread (instead of the
  application thread).

  This example uses a static UDP interface configuration. Using this API, the
  UDP transport is statically configured. This is useful in systems that are
  not able to return the installed UDP interfaces (name, IP address, mask, etc.).

- **zerocopy**

  Identical to the default template, except that the only transport used is
  Zero Copy v2. The UDP transport remains enabled because it is used for
  DDS discovery.

  Both the publisher and subscriber applications must run in the same OS
  instance.

How to compile the generated examples
-------------------------------------

Before compiling, set the environment variable ``RTIMEHOME`` to the |me| installation
directory. 

The |me| source bundle includes rtime-make to simplify invoking CMake. This
script is a convenient way to invoke CMake with the correct options. For example:

.. code-block:: console

  cd <directory with generated example>

  rtime-make --config <Debug|Release> --build --target armv8leElfgcc7.3.0-Linux4 --source-dir . \
       -G "Unix Makefiles" --delete [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE_eq_true]

.. warning::

    RTI recommends using the toolchain file that matches the target architecture
    to compile the generated examples.
    
    For example, if the target architecture is ``--target armv8leElfgcc7.3.0-Linux4``,
    then the example applications should be compiled with the
    ``armv8leElfgcc7.3.0-Linux4`` toolchain file. Failing to do so may cause warnings. 

The executable can be found in the ``objs`` directory.

The following options are accepted:

- ``-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE=true`` adds a rule to regenerate
  type support plugin source files if the input file with the type definition changes.
  Default value is 'false'.

How to run the generated examples
---------------------------------

.. note::

  The examples are hard coded to use the loopback address 127.0.0.1.

Run the subscriber with this command:

  .. code-block:: console

    objs/armv8leElfgcc7.3.0-Linux4/<Type definition file name>_subscriber [-domain <Domain_ID>] [-peer <address>] \
                 [-sleep <sleep_time>] [-count <seconds_to_run>]

and run the publisher with this command:

  .. code-block:: console

    objs/armv8leElfgcc7.3.0-Linux4/<Type definition file name>_publisher [-domain <Domain_ID> -peer <address>] \
                 [-sleep <sleep_time>] [-count <seconds_to_run>]