.. _example_generation:

Example Applications
====================

The RTI *Code Generator* (*rtiddsgen*) can generate example applications from an
IDL file, as shown in :ref:`section-helloworld-pubsub`. The last type in the IDL
is used as the data-type to publish. Refer to
:ref:`section-generating-examples` for instructions on how to build these
examples.

|me| also provides some buildable applications in the installation directory,
as described in :ref:`section-provided-examples`.

.. _section-generating-examples:

Generating examples
-------------------

.. 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|C++> [-namespace] <file with type definition>

This 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 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|C++> [-namespace] <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 ``waitsets`` custom template instead of the default template:

.. code-block:: console

    List of example templates per language:
        - C:
            - cert
            - dpse
            - shared_memory
            - static_udp
            - waitsets
            - crc
            - zcv2
            - mag/shared_memory
            - mag/static_udp
            - mag/dpde
            - mag/dpse
            - psk
        - C++:
            - dpse
            - waitsets
            - mag/dpde
        - 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:

.. code-block:: console

    rtiddsgen -example -exampleTemplate waitsets -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 :ref:`dynamic_endpoint_disc` (DPDE). 
  Only the :ref:`UDP <section-udp-transport>` and
  :ref:`INTRA <section-intra-transport>` 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**
    
  Discovery of endpoints is done with the :ref:`static_endpoint_disc` (DPSE).
  Static-endpoint discovery uses function calls to statically assert information
  about remote endpoints belonging to remote *DomainParticipants*.

- **shared_memory**
    
  The only transport used is shared memory. Because the
  :ref:`section-udp-transport` is disabled and only
  the :ref:`section-shared-memory-transport` is enabled, both the publisher and
  subscriber applications need to run in the same operating system.

- **static_udp**
  
  This example uses a static :ref:`section-udp-transport` 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.).

- **waitsets**
    
  In this example, the Subscriber application creates a *DataReader* that uses a
  :link_connextmicro_dds_api_c_up_one:`Waitset <group__DDSConditionsModule.html>`
  (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).

- **crc**
  
  This example includes configuration of the :ref:`msgintegrity` settings. The
  CRC fields in the :link_connextmicro_dds_api_c_up_one:`WireProtocolQosPolicy <structDDS__WireProtocolQosPolicy.html>`
  enable generating a checksum value based on the data being transmitted. They
  also determine which checksums are allowed and whether they should be sent.

- **zcv2**
  
  This example uses the :ref:`section-zero-copy-v2-transport` and handles
  discovery over the :ref:`section-udp-transport`. User traffic
  is handled using the Zero Copy v2 interface.

- **psk**

  This example uses pre-shared key (PSK) encryption to secure communications.
  You must have the :ref:`section-psk` installed in order to compile this
  example.

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 (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

        .. 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=true]

    .. group-tab:: macOS

        .. code-block:: console

            cd <directory with generated example>

            rtime-make --config <Debug|Release> --build --target x86_64leMachOclang15.0-Darwin23 --source-dir . \
                 -G "Unix Makefiles" --delete [-DRTIME_IDL_ADD_REGENERATE_TYPESUPPORT_RULE=true]

    .. group-tab:: Windows

        .. code-block:: console

            cd <directory with generated example>

            rtime-make.bat --config <Debug|Release> --build --target x86_64lePEvs2017-Win10 --source-dir . \
                 -G "Visual Studio 15 2017" --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 directory 'objs'.

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

.. 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=armv8leElfgcc7.3.0-Linux4

            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=x86_64leMachOclang15.0-Darwin23

            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 15 2017" -B./<your build directory> -H. -DRTIME_TARGET_NAME=x86_64lePEvs2017-Win10

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

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. Use the option 
``-udp_intf <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:

  .. 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>] [-udp_intf <interface name>]

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>] [-udp_intf <interface name>]

.. note::
  
  Shared memory examples only accept the following options: 
  
  * ``[-domain <Domain_ID>]``
  * ``[-sleep <sleep_time>]``
  * ``[-count <seconds_to_run>]``

.. _section-provided-examples:

Provided examples
-----------------

|me| provides buildable example applications in the ``example/`` directory
of your installation. Each example demonstrates different features, as 
described below:

- **HelloWorld_transformations**: A HelloWorld example that uses
  :ref:`UDP transformations <section-udp-transform>` to send encrypted packets
  using OpenSSL.
- **HelloWorld_dgram**: A HelloWorld example that uses an example
  :ref:`DGRAM <transport_netio_dgram>` implementation. 

Consult the ``README.txt`` file included with each example for instructions 
on how to build and run the application.