.. _opendds_idl: ############### ``opendds_idl`` ############### .. program:: opendds_idl .. Sect<8> ``opendds_idl`` is one of the code generators used in the process of building OpenDDS and OpenDDS applications. It can be used in a number of different ways to customize how source code is generated from :term:`IDL` files. See :ref:`getting_started--processing-the-idl` for an overview of the default usage pattern. The OpenDDS IDL compiler is invoked using the ``opendds_idl`` executable, located in :ghfile:`bin/` (on the ``PATH``). It parses a single IDL file and generates the serialization and key support code that OpenDDS requires to marshal and demarshal the types described in the IDL file, as well as the type support code for the data readers and writers. For each IDL file processed, such as ``xyz.idl``, it generates three files: ``xyzTypeSupport.idl``, ``xyzTypeSupportImpl.h``, and ``xyzTypeSupportImpl.cpp``. In the typical usage, ``opendds_idl`` is passed a number of options and the IDL file name as a parameter. For example, .. code-block:: bash opendds_idl [options...] Foo.idl Subsequent sections describe all of the command-line options and the ways that ``opendds_idl`` can be used to generate alternate mappings. .. _opendds_idl--opendds-idl-command-line-options: ************************************ ``opendds_idl`` Command Line Options ************************************ .. Sect<8.1> .. option:: --help, -h Prints a help message and exits. .. option:: -v Enables verbose/debug logging. .. option:: --version, -V Prints version numbers of both TAO and OpenDDS. .. option:: --idl-version VERSION Set the version of the :ref:`IDL specification ` to use. The default is ``4``. .. option:: --list-idl-versions List the versions of IDL at least partially supported and exits. .. option:: --syntax-only Just check syntax of input files and exit without generating any code. .. option:: -Wb,export_macro=MACRO Use the export macro for generating C++ implementation code named *MACRO*. By default export macros are not used. ``--export`` is an alias for this. .. option:: -Wb,export_include=FILE Add an additional header *FILE* to ``#include`` in generated code that has the export macro. .. option:: -Wb,pch_include=FILE Include a pre-compiled header *FILE* in generated C++ files. .. option:: -Dname[=value] Define a preprocessor macro named *name* optionally with value *value* for IDL. .. option:: -Idir Adds *dir* to the preprocessor include path for IDL. .. option:: -o OUTPUT_PATH Output directory where generated files are put. By default this is the current working directory. .. option:: -Wb,java Generate Java Bindings for generated ``TypeSupport`` implementation classes. See :ref:`java` for more information. .. option:: -Gitl Generate "Intermediate Type Language" descriptions of topic types. These files are used by the Wireshark dissector or other external applications. .. option:: -GfaceTS Generate FACE (Future Airborne Capability Environment) Transport Services API. See :doc:`safety_profile` for more information. .. option:: -Gxtypes-complete Generate complete XTypes TypeObjects which can be used to provide type information to applications that don't have compile-time knowledge of the IDL. By default only minimal TypeObjects are generated. See :ref:`xtypes--dynamic-language-binding-1` for more information. .. option:: -Gequality Generate ``==`` and ``!=`` for structs and unions. The members of the struct or union must have a type that could appear in a DDS topic and be supported by ``opendds_idl``. .. option:: -Lface Generates IDL-to-C++ mapping for FACE. See :doc:`safety_profile` for more information. .. option:: -Lspcpp Generates IDL-to-C++ mapping for :doc:`safety_profile`. .. option:: -Lc++11 Generates :ref:`IDL-to-C++11 mapping `. .. option:: -Wb,tao_include_prefix=S Prefix the string *S* to ``#include`` directives meant to include headers generated by ``tao_idl``. .. option:: -SI Suppress generation of the TypeSupport.idl file. .. option:: -Sv Suppress generation of Value Reader/Writer support code. .. option:: -Sx Suppress generation of XTypes Type Objects. .. option:: -St Suppress generation of IDL TypeCodes when one of the ``-L*`` options are present. .. option:: -Sdefault Suppress all default code generation passes. Use ``-G*`` options and other options to enable selective code generation. Default code generation passes include (at least): XTypes Type Objects, Value Reader/Writer support, Marshalling (serialization), DCPS keys, Type Support, Content-Subscription Profile support, XTypes Dynamic Data support. .. option:: --unknown-annotations REACTION Control the reaction to unknown IDL annotations. *REACTION* can be: * ``warn-once`` -- the default, warn once per annotation with the same name. * ``warn-all`` -- warn for every use of an unknown annotation. * ``error`` -- similar to ``warn-all``, but causes the compiler to exit with an error status when finished. * ``ignore`` -- ignore all unknown annotations. .. option:: --no-dcps-data-type-warnings Don't warn about ``#pragma DCPS_DATA_TYPE``. See :ref:`getting_started--identifying-topic-types` for more information. .. option:: --default-nested .. option:: --no-default-nested Un-annotated types/modules are treated as nested. By default all types are nested. See :ref:`getting_started--topic-types-vs-nested-types` for details. .. option:: --default-extensibility EXT Set the :ref:`default XTypes extensibility `. *EXT* can be: - ``final`` - ``appendable`` (default) - ``mutable`` .. option:: --default-autoid VALUE Set the default :ref:`XTypes auto member-id assignment strategy `. *VALUE* can be ``sequential`` (the default) or ``hash``. .. option:: --default-try-construct VALUE Set the default :ref:`XTypes try-construct strategy `. *VALUE* can be ``discard`` (the default), ``use-default``, or ``trim``. .. option:: --old-typeobject-encoding .. versionadded:: 3.18 Use the pre-3.18 encoding of ``TypeObject``\s when deriving ``TypeIdentifier``\s. .. option:: --default-enum-extensibility-zero .. versionadded:: 3.22 Do not set the type flags for enums. This flag is for simulating the behavior of OpenDDS before 3.22. .. option:: --old-typeobject-member-order .. versionadded:: 3.24 Use the pre-3.24 struct and union member order for ``TypeObject``\s, which is ordered by member id instead of declared order. See :ref:`3.24.0 news entry <3-24-0-typeobject-fix>` for more info. .. option:: -Gtypeobject Generate XTypes Type Objects. This option is only useful along with :option:`-Sdefault` because Type Objects are generated by default. .. option:: --append-typeobjects FILE Open *FILE* in append mode and write Type Objects (as byte arrays) to the file. This is in addition to normal code generation. The code generation options allow the application developer to use the generated code in a wide variety of environments. Since IDL may contain preprocessing directives (``#include``, ``#define``, etc.), the C++ preprocessor is invoked by ``opendds_idl``. The ``-I`` and ``-D`` options allow customization of the preprocessing step. The ``-Wb,export_macro`` option lets you add an export macro to your class definitions. This is required if the generated code is going to reside in a shared library and the compiler (such as Visual C++ or GCC) uses the export macro (``dllexport`` on Visual C++ / overriding hidden visibility on GCC). The ``-Wb,pch_include`` option is required if the generated implementation code is to be used in a project that uses precompiled headers. .. _opendds_idl--using-the-idl-to-c-11-mapping: ****************************** Using the IDL-to-C++11 Mapping ****************************** .. Sect<8.2> The :ref:`IDL-to-C++11 Mapping ` is a separate specification from the OMG. Like the "classic" IDL-to-C++ Mapping, IDL-to-C++11 describes how IDL constructs (structs, sequences, unions, etc.) should appear in C++. Since the IDL-to-C++11 Mapping assumes a C++11 (or higher) compiler and standard library, the code generated is easier to use and looks more natural to C++ developers who are not familiar with the classic mapping. For example, IDL strings, arrays, sequences, and maps map to their equivalents in the ``std`` namespace: ``string``, ``array``, ``vector``, and ``map``. All of the details of the mapping are spelled out in the specification document (available at https://www.omg.org/spec/CPP11), however the easiest way to get started with the mapping is to generate code from IDL and examine the generated header file. In the default mode of ``opendds_idl`` (as described in :ref:`getting_started--processing-the-idl`), responsibility for generating the language mapping is delegated to ``tao_idl`` (using the IDL-to-C++ classic mapping). In this case, ``opendds_idl`` is only responsible for generating the OpenDDS-specific additions such as ``TypeSupport.idl`` and the marshal/demarshal functions. Contrast this with using ``opendds_idl`` for IDL-to-C++11. In this case, ``opendds_idl`` takes over responsibility for generating the language mapping. This is indicated by the ``-Lc++11`` command-line option. Starting with a user-written file ``Foo.idl``, running ``opendds_idl -Lc++11 Foo.idl`` generates these output files: * ``FooTypeSupport.idl`` * IDL local interfaces for ``*TypeSupport``, ``*DataWriter``, ``*DataReader`` * ``FooC.h`` * IDL-to-C++11 language mapping * ``FooTypeSupportImpl.h and .cpp`` * Additional source code needed for OpenDDS FooTypeSupport.idl is the same as it was when using the classic mapping. After it's generated by ``opendds_idl``, it needs to be processed by ``tao_idl`` to generate ``FooTypeSupportC.h``, ``FooTypeSupportC.inl``, and ``FooTypeSupportC.cpp``. Unlike when using the classic mapping, ``Foo.idl`` is not processed by ``tao_idl``. ``Foo.idl`` can contain the following IDL features: * modules, typedefs, and constants * basic types * constructed types: enums, structs and unions * Note that setting a union value through a modifier method automatically sets the discriminator. In cases where there are multiple possible values for the discriminator, a 2-argument modifier method is provided. Using this is preferred to using ``_d()``. * If you chose to use the ``_d()`` method of the generated union types, take note that it can only be used to set a value that selects the same union member as the one that's currently selected. OpenDDS treats this as a precondition (it is not checked within the implementation). * strings (narrow and wide), sequences, maps, and arrays * Bounded strings and sequences are supported, but bounds checks are not currently enforced. Due to this limitation, distinct types are not used for bounded instantiations. * annotations -- see :ref:`getting_started--defining-data-types-with-idl` and :ref:`xtypes--idl-annotations` * ``#include``\s of IDL files that are also used with the IDL-to-C++11 mapping When using MPC to generate projects, the ``opendds_cxx11`` base project should be used to inherit the correct settings for code generation. If the generated code will be part of a shared library, use the ``-Wb,export_include`` option (in addition to ``-Wb,export_macro``) so that the generated headers have an ``#include`` for the export header. When using CMake to generate projects, see :doc:`/devguide/building/cmake`. .. _opendds_idl--usage: ********* IDL Usage ********* .. _opendds_idl--annotations: Annotations =========== .. Sect<16.6> In IDL, annotations are a way of indicating meta-information about a type or part of a type. They usually precede what is being annotated and start with a ``@`` followed by the name of the annotation and optionally arguments like a function call. For example: .. code-block:: omg-idl @topic @mutable struct TopicType { @id(100) int32 value; }; .. _opendds_idl--xtypes-annotations: XTypes Annotations ------------------ See :ref:`here ` for annotations related to XTypes. .. _opendds_idl--opendds-specific-annotations: OpenDDS-Specific Annotations ---------------------------- .. _opendds_idl-opendds-no_init_before_deserialize: ``@OpenDDS::no_init_before_deserialize`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Applies to: sequence typedefs, anonymous sequence struct members, anonymous sequence union members (only when :ref:`opendds_idl--using-the-idl-to-c-11-mapping`) .. important:: Builds using the IDL-to-C++11 mapping will probably need to be optimized to get any benefit from this, otherwise the deserialization will probably be slower. When deserializing a very large sequence of primitive values, a significant portion of time could be spent zero-initializing the memory of the receiving type before setting the actual values. Zero-initializing in this case isn't required because all the elements are going to be set. While the classic TAO mapping can avoid this without any user intervention, the :ref:`IDL-to-C++11 mapping ` requires a special ``std::vector`` type with a custom allocator to do this. This is not the default because of potential slowdown and the fact this type will not be assignable with normal ``std::vector`` types as it's using a custom allocator. .. versionadded:: 3.34.0