.. _example_generation:

Example Generation
==================

The RTI Code Generator available with |me| can generate DDS example applications
with a type definition file as input.

Note that before running *rtiddsgen*, you might need to add
<|me| install folder>/rtiddsgen/scripts to your path environment variable folder.

To generate an example::

    rtiddsgen -example -language <C|C++> [-namespace] <file with type definition>

This command generates an example using the default example template, which uses
the Dynamic Participant Dynamic Endpoint (DPDE) discovery plugin.

*rtiddsgen* accepts the following options:

-  ``-example``: Generates type files, example files, and CMakelists files.

-  ``-language <C|C++>``: Generates C or C++ code.
    
-  ``-namespace``: Enables C++ namespaces when the language option is C++.

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

The RTI Code Generator can also generate examples using custom templates by
using the option ``-exampleTemplate <templateName>``.

To generate an example using a custom template instead of the default one::

    rtiddsgen -example -exampleTemplate <template name> -language <C|C++> [-namespace] <file with type definition>

To see the list of the available templates, use the following command::

    rtiddsgen -showTemplates

The output from the command will look similar to this:

.. only:: micro2

    .. code-block:: console

        List of example templates per language:
            - C:
                - cert
                - dpse
                - static_udp
                - waitsets
            - C++:
                - dpse
                - waitsets
            - C++ Namespace:
                - dpse
                - waitsets

.. only:: micro3

    .. code-block:: console

        List of example templates per language:
            - C:
                - cert
                - dpse
                - mag/dpde
                - mag/dpse
                - mag/shared_memory
                - mag/static_udp
                - secure
                - shared_memory
                - static_udp
                - waitsets
            - C++:
                - dpse
                - mag/dpde
                - secure
                - waitsets
            - C++ Namespace:
                - dpse
                - waitsets

The following command will generate an example in the C language, using the 'waitsets'
custom template instead of the default template::

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


Description of Examples
-----------------------

All examples consist of a publication and subscription pair to send and receive
the type provided by user. Two applications are compiled: one to send samples and
another to receive samples.

- **Default template**
    Discovery of endpoints is done with the dynamic-endpoint discovery. 
    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).

- **cert**
    An example that only uses APIs that are compatible with |me_cert|.

- **dpse**
    The only difference from the default template is that the discovery of endpoints
    is done with static-endpoint discovery. Static-endpoint discovery uses
    function calls to statically assert information about remote endpoints
    belonging to remote DomainParticipants.

.. only:: micro3

    - **secure**
        The only difference from the default template is that this example uses secure
        communication.

    - **shared_memory**
        The only difference from the default template is that the only transport used is
        shared memory. Because the UDP transport is disabled and only the shared memory transport
        is enabled, both the publisher and subscriber applications need to run in the same
        OS.

- **static_udp**
    The only difference from the default template is that 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...).

- **waitsets**
    The only difference from the default template is that the Subscriber application
    creates a DataReader that uses a Waitset (instead of a listener) to receive
    notifications about new samples and matched publishers. These notifications are
    received in the middleware thread (instead of the application thread).

.. only:: micro3

    - **mag**
        All the example templates whose names start with 'mag' use the Micro Application Generator (MAG)
        to create the DDS entities. This means that the DDS entities and their configuration
        are generated from an XML file, instead of by calling DDS APIs in the application. 

    - **mag/dpde**
        The same as the default template, but DDS entities are created by using MAG instead of
        by calling by calling DDS APIs in the application. 

    - **mag/dpse**
        The same as the 'dpse' template, but DDS entities are created by using MAG instead of
        by calling DDS APIs in the application. 

    - **mag/shared_memory**
        The same as the 'shared_memory' template, but DDS entities are created by using MAG
        instead of by calling DDS APIs in the application. 

    - **mag/static_udp**
        The same as the 'static_udp' template, but DDS entities are created by using MAG
        instead of by calling DDS APIs in the application. 

How to Compile the Generated Examples
-------------------------------------

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

Depending on the number of network interfaces installed on the local machine,
you might need to restrict which interfaces are used by |me|. 

.. only:: micro3

   For a 'mag' example, you can find the setting in the file
   '<File name used to generate example>Qos.xml' in the XML element 
   <allow_interfaces_list>. For other (non-'mag') examples, use the
   option ``-udp_interface <interface name>`` when running the example.

.. only:: micro2
   
   Use the option ``-udp_interface <interface name>`` when running the example.

The |me| source bundle includes rtime-make (on Linux and macOS systems) or
rtime-make.bat (on Windows systems) to simplify invocation of CMake. This
script is a convenient way to invoke CMake with the correct options. For example:

.. tabs::

    .. group-tab:: Linux

        .. only:: micro3

            .. code-block:: console

                cd "<${envMap.idlFileName}Application directory>"

                rtime-make --config <Debug|Release> --build --name x64Linux3gcc4.8.2 --target Linux --source-dir . \
                     -G "Unix Makefiles" --delete [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE=true] \
                     [-DRTIME_MAG_FILES=<XML file>] [-DRTIME_LINK_SHMEM_LIBS=true]

        .. only:: micro2

            .. code-block:: console

                cd "<${envMap.idlFileName}Application directory>"

                rtime-make --config <Debug|Release> --build --name x64Linux3gcc4.8.2 --target Linux --source-dir . \
                     -G "Unix Makefiles" --delete [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE=true]

    .. group-tab:: macOS

        .. only:: micro3

            .. code-block:: console

                cd "<${envMap.idlFileName}Application directory>"

                rtime-make --config <Debug|Release> --build --name x64Darwin17.3.0Clang9.0.0 --target Darwin --source-dir . \
                     -G "Unix Makefiles" --delete [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE=true] \
                     [-DRTIME_MAG_FILES=<XML file>] [-DRTIME_LINK_SHMEM_LIBS=true]

        .. only:: micro2

            .. code-block:: console

                cd "<${envMap.idlFileName}Application directory>"

                rtime-make --config <Debug|Release> --build --name x64Darwin17.3.0Clang9.0.0 --target Darwin --source-dir . \
                      -G "Unix Makefiles" --delete [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE=true]

    .. group-tab:: Windows

        .. only:: micro3

            .. code-block:: console

                cd "<${envMap.idlFileName}Application directory>"

                rtime-make.bat --config <Debug|Release> --build --name i86Win32VS2010 --target Windows --source-dir . \
                     -G "Visual Studio 10 2010" --delete [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE_eq_true] \
                     [-DRTIME_MAG_FILES_eq_<XML file>] [-DRTIME_LINK_SHMEM_LIBS_eq_true]

        .. only:: micro2

            .. code-block:: console

                cd "<${envMap.idlFileName}Application directory>"

                rtime-make.bat --config <Debug|Release> --build --name i86Win32VS2010 --target Windows --source-dir . \
                     -G "Visual Studio 10 2010" --delete [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE_eq_true]

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


It is also possible to compile using CMake, e.g., when the |me| source bundle is
not installed.

.. only:: micro2

    .. tabs::

        .. group-tab:: Linux

            .. code-block:: console

                cmake [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE=true] [-DCMAKE_BUILD_TYPE=<Debug|Release>] -G "Unix Makefiles" \
                      -B./<your build directory> -H. -DRTIME_TARGET_NAME=x64Linux3gcc4.8.2"

                cmake --build ./<your build directory> [--config <Debug|Release>]


        .. group-tab:: macOS

            .. code-block:: console

                cmake [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE=true] [-DCMAKE_BUILD_TYPE=<Debug|Release>] -G "Unix Makefiles" \
                      -B./<your build directory> -H. -DRTIME_TARGET_NAME=x64Darwin17.3.0Clang9.0.0"

                cmake --build ./<your build directory> [--config <Debug|Release>]


        .. group-tab:: Windows

            .. code-block:: console

                cmake [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE=true] [-DCMAKE_BUILD_TYPE=<Debug|Release>] -G "Visual Studio 10 2010" \
                      -B./<your build directory> -H. -DRTIME_TARGET_NAME=i86Win32VS2010"

                cmake --build .\<your build directory> [--config <Debug|Release>]


.. only:: micro3

    .. tabs::

        .. group-tab:: Linux

            .. code-block:: console

                cmake [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE=true] [-DRTIME_MAG_FILES=<XML file>] [-DRTIME_LINK_SHMEM_LIBS=true] \
                      [-DCMAKE_BUILD_TYPE=<Debug|Release>] -G "Unix Makefiles" -B./<your build directory> -H. -DRTIME_TARGET_NAME=x64Linux3gcc4.8.2"

                cmake --build ./<your build directory> [--config <Debug|Release>]


        .. group-tab:: macOS

            .. code-block:: console

                cmake [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE=true] [-DRTIME_MAG_FILES=<XML file>] [-DRTIME_LINK_SHMEM_LIBS=true] \
                      [-DCMAKE_BUILD_TYPE=<Debug|Release>] -G "Unix Makefiles" -B./<your build directory> -H. -DRTIME_TARGET_NAME=x64Darwin17.3.0Clang9.0.0"

                cmake --build ./<your build directory> [--config <Debug|Release>]


        .. group-tab:: Windows

            .. code-block:: console

                cmake [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE=true] [-DRTIME_MAG_FILES=<XML file>] [-DRTIME_LINK_SHMEM_LIBS=true] \
                      [-DCMAKE_BUILD_TYPE=<Debug|Release>] -G "Visual Studio 10 2010" -B./<your build directory> -H. -DRTIME_TARGET_NAME=i86Win32VS2010"

                cmake --build .\<your build directory> [--config <Debug|Release>]


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

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'.

.. only:: micro3

    - ``-DRTIME_MAG_FILES=<XML file with Application Generation definitions>`` adds
      a rule to generate application support files from XML. 

    - ``-DRTIME_LINK_SHMEM_LIBS=true`` adds a dependency to the shared memory transport
      libraries. This option shall be used only with the shared memory example.
      The default value is 'false'.

How to Run the Generated Examples
---------------------------------

By default, the example uses all available interfaces to receive samples. This can
cause communication problems if the number of available interfaces is greater than
the maximum number of interfaces supported by |me|. For this reason, it is recommended
to restrict the number of interfaces used by the application. 

.. only:: micro3

   For a 'mag' example, you can find the setting in the file 
   '<File name used to generate example>Qos.xml'
   in the XML element <allow_interfaces_list>. 
   For other (non-'mag') examples, use the option 
   ``-udp_interface <interface name>`` when running the example.
   
.. only:: micro2

   Use the option ``-udp_interface <interface name>`` when running the example.

For example, if the example has been compiled for Linux i86Linux2.6gcc4.4.5, run
the subscriber with this command: ::

    objs/x64Linux3gcc4.8.2/<Type definition file name>_subscriber [-domain <Domain_ID>] [-peer <address>] \
                 [-sleep <sleep_time>] [-count <seconds_to_run>] [-udp_intf <interface name>]

and run the publisher with this command: ::

    objs/x64Linux3gcc4.8.2/<Type definition file name>_publisher [-domain <Domain_ID> -peer <address>] \
                 [-sleep <sleep_time>] [-count <seconds_to_run>] [-udp_intf <interface name>]

.. only:: micro3

    Note that shared memory examples only accept the following options: 
    ``[-domain <Domain_ID>]``, ``[-sleep <sleep_time>]`` and ``[-count <seconds_to_run>]``.

    MAG examples only accept the following options: 
    ``[-sleep <sleep_time>]`` and ``[-count <seconds_to_run>]``.