.. _section-protobuf-ext-components:

|PROTOBUF_EXT_HEADING| Components
*********************************


|PROTOBUF_EXT| consists of two RTI plugins for 
``protoc`` and a set of DDS-specific options for |PROTOBUF| types.

.. _section-idl4-plugin:

|IDL| Converter Plugin
======================

The |PROTOBUF_EXT| |IDL| Converter Plugin (``idl4``) converts ``.proto`` 
files into equivalent ``.idl`` files using the ``--idl4_out`` ``protoc`` 
option. For example:

.. code-block:: shell

    protoc --idl4_out=<outputdir> message.proto


* Example input (``message.proto``):

  .. code-block:: protobuf

      syntax = "proto3";

      import "other.proto";

      package myapp;

      message MyMessage {
          int32 foo = 1;
          Other bar = 2;
      }

* Example output (``message.idl``):

  .. code-block:: omg-idl

      #ifndef myapp_message_proto_IDL4_
      #define myapp_message_proto_IDL4_

      #include "other.idl"

      module myapp {
          @mutable
          struct MyMessage {
              @id(1) int32 foo;
              @id(2) @optional Other bar;
          };
      }; // module myapp

      #endif // myapp_message_proto_IDL4_

See :ref:`section-proto2idl` for a detailed description of the
mapping between |PROTOBUF| and |IDL| types.

.. _section-connext-cpp-plugin:

C++ Code Generator Plugin
=========================

|RTI_CODEGEN| (``rtiddsgen``) includes the |CONNEXT| C++ Code Generator Plugin 
(``connext-cpp``) to generate C++ source code from IDL files. This plugin 
works together with the |PROTOBUF| built-in C++ code generator to 
create C++ classes for each data type in a ``.proto`` file. For example:

.. code-block:: shell

    protoc --cpp_out=<outputdir> \
            --connext-cpp_out=<outputdir> \
            message.proto

Example output (``message.pb.h``, abridged):

.. code-block:: c++

    #include "other.pb.h"

    // Injected by RTI code generator
    #include "rti/topic/cdr/ProtobufInterpreter.hpp"

    namespace myapp {

    class MyMessage final : public ::google::protobuf::Message {
    public:
        MyMessage();
        ~MyMessage() override;

        bool has_foo() const;
        void clear_foo();
        int32_t foo() const;
      
        bool has_bar() const;
        void clear_bar();
        const ::myapp::Other& bar() const;
        ::myapp::Other* mutable_bar();
        void set_allocated_bar(::myapp::Other* bar);

        // Injected by RTI code generator
        template <typename MessageType>
        friend struct ::rti::topic::interpreter::detail::protobuf_message_access;

    private:
        int32_t foo_;
        ::myapp::Other* bar_;
    }

    } // namespace myapp


.. _section-dds-options-intro:

DDS Options for |PROTOBUF|
==========================

Custom options are available to control |IDL| types derived 
from |PROTOBUF| definitions. These DDS-specific 
options are defined using |PROTOBUF| syntax and become available
after importing RTI's supporting ``omg/dds/descriptor.proto`` file.

* Example input (``message.proto``, annotated):

  .. code-block:: protobuf

      syntax = "proto3";
  
      import "other.proto";

      import "omg/dds/descriptor.proto";

      package myapp;

      message MyMessage {
          option (.omg.dds.type) = {
              default_id: DDS_DEFAULT_ID,
              auto_id: HASH
          };

          int32 foo = 1 [ (.omg.dds.member).key = true ];
          Other bar = 2 [ (.omg.dds.member) = {
            optional: true,
            hash_id: "baz"
          }];
      }
  
* Example output (``message.idl``, customized):

  .. code-block:: omg-idl

      #ifndef myapp_message_proto_IDL4_
      #define myapp_message_proto_IDL4_

      #include "other.idl"
  
      module myapp {
          @mutable
          @autoid(hash)
          struct MyMessage {
              @key int32 foo;
              @hash_id("baz") Other bar;
          };
      }; // module myapp

      #endif // myapp_message_proto_IDL4_

See :ref:`section-dds-options` for detailed information about the RTI descriptor file.

.. _section-components-path:

Accessing the RTI Plugins
=========================

The |PROTOBUF| plugins, ``idl4``
and ``connext-cpp``, are located in ``<NDDSHOME>/bin``. To make them 
accessible to ``protoc``, add this directory to your ``PATH`` environment 
variable. For example:

.. code-block:: bash

    export PATH=<NDDSHOME>/bin:$PATH

Alternatively, specify the explicit path of each plugin using the 
``protoc`` command:

.. code-block:: shell

    protoc --plugin=<NDDSHOME>/bin/protoc-gen-idl4 \
           --plugin=<NDDSHOME>/bin/protoc-gen-connext-cpp \
           ...

Limitations
===========

The current versions of the RTI plugins for ``protoc`` have the
following known limitations:

Platforms and compatibility
---------------------------

The RTI plugins are included in the installer for Linux and macOS. 
While these are the primary platforms where the plugins are installed, 
RTI has also tested the generated code's compatibility with QNX 8 builds. 
The generated code is expected to be compatible with Windows; however, 
this platform has not yet been formally tested by RTI.

Recursive types
---------------
The |IDL| Converter Plugin does not support recursive types, 
such as a message that contains a field of its own type.