.. _section-what-is-protobuf-ext: About |PROTOBUF_EXT_HEADING| **************************** |RTI_TM_CONNEXT_TM| |PROTOBUF_EXT| enables using |PROTOBUFS_TM| data types in |CONNEXT| applications. Use Cases ========= Protocol buffers definition language support -------------------------------------------- |PROTOBUF_EXT| enables developers to use the Protocol Buffers (``protobuf``) message definition language to define the data types used by |CONNEXT| applications. The toolchain automatically maps ``protobuf`` types to corresponding |DDS-XTYPES| types, which serve as the foundation for communication over DDS. .. figure:: static/Protobuf_to_IDL.png :alt: Protocol Buffers to |IDL| Conversion :name: Figure - Protocol Buffers to |IDL| Conversion :align: center :figWidth: 100% DDS-XTYPES type generation -------------------------- |PROTOBUF_EXT| generates ``.idl`` files containing |DDS-XTYPES| types equivalent to the Protocol Buffers types defined in ``.proto`` files. This conversion enables seamless interoperability between |CONNEXT| applications using |PROTOBUF| data types and those using equivalent DDS-XTYPES, regardless of the programming language used. Protocol Buffers C++ language binding ------------------------------------- |PROTOBUF_EXT| allows developers to use the C++ message types generated by the protocol buffers compiler (``protoc``) in combination with |CONNEXT|'s `Modern C++ API `__. Applications can create |DW| and |DR| endpoints to exchange objects of the Protocol Buffers types directly over DDS |TOPICS|. Existing components that use these types can be easily and efficiently integrated onto the DDS databus. .. figure:: static/Protobuf_Databus.png :alt: Protocol Buffers Integration with DDS :name: Figure - Protocol Buffers Integration with DDS :align: center :figWidth: 100% Integration with DDS -------------------- The data types defined using Protocol Buffers are first-class citizens in the |CONNEXT| platform and can be used just like other DDS types. Full support is provided for features such as type discovery, type matching, type evolution, dynamic types, dynamic data, content filtering, and more. The ``.proto`` files can be enriched with custom |PROTOBUF_EXT| options defined to control DDS-specific properties, such as indicating key members. Other options allow developers to take advantage of |DDS-XTYPES| features not natively available in Protocol Buffers. These features enhance the integration of |PROTOBUF_EXT| components with other |CONNEXT| applications. .. _section-components: Components ========== |PROTOBUF_EXT| consists of two RTI components and a set of DDS-specific options: - The :ref:`IDL4 Converter Plugin ` converts ``.proto`` files into equivalent ``.idl`` files. - The :ref:`C++ Code Generator Plugin ` generates C++ source code from ``.proto`` files. - :ref:`DDS Options for Protocol Buffers ` types customizes the generated |IDL| types using DDS-specific options defined in ``.proto`` files. .. _section-installation: System Requirements =================== To use |PROTOBUF_EXT| successfully, your system must meet the following requirements: - |PRO| is installed on a supported operating system (see :ref:`Supported Platforms `) and the :link_connext_dds_pro_gsg_cpp11:`RTI environment variables ` are set. - The `protocol buffer compiler `__ (``protoc``) is installed and available in your system's ``PATH``. |PROTOBUF_EXT| supports ``protoc`` versions 3.12.0 through 33.0. - ``/bin`` is included in your system's ``PATH``. - The RTI ``/resource/proto/omg/dds/descriptor.proto`` file is available to ``protoc``. This file is included in the |CONNEXT| installation. For more detail about these requirements, see :ref:`section-before-you-begin`. |PROTOBUF_EXT| is pre-installed as part of |PRO|. For instructions to install |CONNEXT|, see the :link_connext_dds_pro_ig:`RTI Connext Professional Installation Guide `. .. _section-paths-mentioned: Paths Mentioned in Documentation ================================ This documentation refers to |CONNEXT| installation and example paths using the following conventions: - ```` refers to the installation directory for |CONNEXT|. The default installation paths are: - macOS® systems: ``/Applications/rti_connext_dds-`` - Linux® systems, non-root user: ``/home/your user name/rti_connext_dds-`` - Linux systems, root user: ``/opt/rti_connext_dds-`` - Windows® systems, user without Administrator privileges: ``\rti_connext_dds-`` - Windows systems, user with Administrator privileges: ``C:\Program Files\rti_connext_dds-`` Whenever you see ```` used in a path, replace it with your installation path. You may also see ``$NDDSHOME`` or ``%NDDSHOME%``, which refers to an environment variable set to the installation path. - ```` refers to the directory for |CONNEXT| example files. By default, examples are copied into your home directory the first time you run *RTI Launcher* or any script in ``/bin``. This document refers to the location of the copied examples as ````. The default paths to the examples are: - macOS systems: ``/Users/your user name/rti_workspace//examples`` - Linux systems: ``/home/your user name/rti_workspace//examples`` - Windows systems: ``your Windows documents folder\rti_workspace\\examples``. Where ``'your Windows documents folder'`` depends on your version of Windows. For example, on Windows 7, the folder is ``C:\Users\your user name\Documents``; on Windows Server 2003, the folder is ``C:\Documents and Settings\your user name\Documents``. Wherever you see ````, replace it with the appropriate path.