.. _opendds_idl--opendds-idl: ########### 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 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> The following table summarizes the options supported by ``opendds_idl``. .. _opendds_idl--reftable29: **Table opendds_idl Command Line Options** .. list-table:: :header-rows: 1 * - Option - Description - Default * - ``-v`` - Enables verbose execution - Quiet execution * - ``-h`` - Prints a help (usage) message and exits - N/A * - ``-V`` - Prints version numbers of both TAO and OpenDDS - N/A * - ``--idl-version VERSION`` - Set the version of IDL to use. - 4 * - ``--list-idl-versions`` - List the versions of IDL at least partially supported. - N/A * - ``--syntax-only`` - Just check syntax of input files, exiting after parsing. - Goes on to generate code * - ``-Wb,export_macro=macro`` - Export macro used for generating C++ implementation code. ``--export`` is equivalent to ``-Wb,export_macro`` - No export macro used * - ``-Wb,export_include=file`` - Additional header to ``#include`` in generated code — this header ``#defines`` the export macro - No additional include * - ``-Wb,pch_include=file`` - Pre-compiled header file to include in generated C++ files - No pre-compiled header included * - ``-Dname[=value]`` - Define a preprocessor macro - N/A * - ``-Idir`` - Add ``dir`` to the preprocessor include path - N/A * - ``-o outputdir`` - Output directory where ``opendds_idl`` should place the generated files. - The current directory * - ``-Wb,java`` - Enable OpenDDS Java Bindings for generated TypeSupport implementation classes - No Java support * - ``-Gitl`` - Generates “Intermediate Type Language” descriptions of datatypes. These files are used by the Wireshark dissector or other external applications. - Not generated * - ``-GfaceTS`` - Generates FACE (Future Airborne Capability Environment) Transport Services API - Not generated * - ``-Gv8`` - Generate type support for converting data samples to/from V8 JavaScript objects ``-Wb,v8`` is an alternative form of this option - Not generated * - ``-Grapidjson`` - Generate type support for converting data samples to/from RapidJSON objects - Not generated * - .. _opendds_idl--gxtypes-complete-option: .. _opendds_idl--gxtypes-complete: ``-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. See :ref:`xtypes--dynamic-language-binding-1`. - Only minimal TypeObjects are generated * - ``-Lface`` - Generates IDL-to-C++ mapping for FACE - Not generated * - ``-Lspcpp`` - Generates IDL-to-C++ mapping for Safety Profile - Not generated * - ``-Lc++11`` - Generates IDL-to-C++11 mapping - Not generated * - ``-Wb,tao_include_prefix=s`` - Prefix the string *s* to #include directives meant to include headers generated by ``tao_idl`` - N/A * - ``-St`` - Suppress generation of IDL TypeCodes when one of the ``-L`` options are present. - IDL TypeCodes generated * - ``--unknown-annotations VAL`` - For IDL version 4, control the reaction to unknown annotations. The options are: * ``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.`` - ``warn-once`` * - ``--no-dcps-data-type-warnings`` - Don't warn about ``#pragma DCPS_DATA_TYPE`` - Warnings are issued, use annotations to silence them * - ``--[no-]default-nested`` - Un-annotated types/modules are treated as nested. See :ref:`getting_started--topic-types-vs-nested-types` for details. - Types are nested by default. * - .. _opendds_idl--default-extensibility: ``--default-extensibility`` - Set the default XTypes extensibility. Can be ``final``, ``appendable`` or ``mutable``. See :ref:`xtypes--extensibility` for details. - ``appendable`` * - ``--default-enum-extensibility-zero`` - Do not set the type flags for enums. This flag is for simulating the behavior of previous versions of OpenDDS. - * - ``--default-autoid VAL`` - Set the default XTypes auto member-id assignment strategy: sequential or hash – see :ref:`xtypes--autoid-value` - ``sequential`` * - ``--default-try-construct VAL`` - Set the default XTypes try-construct strategy: ``discard``, ``use-default``, or ``trim`` – see :ref:`xtypes--customizing-xtypes-per-member` - ``discard`` * - ``--old-typeobject-encoding`` - Use the pre-3.18 encoding of ``TypeObject``\s when deriving ``TypeIdentifier``\s - Use standard encoding * - ``--old-typeobject-member-order`` - Use the pre-3.24 struct and union member order for ``TypeObject``\s, which is ordered by member id instead of declared order. See 3.24.0 news entry for more info. - Use standard declared order 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 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, and sequences map to their equivalents in the ``std`` namespace: ``string``, ``array``, and ``vector``. 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, 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` * #includes 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 the CMake module documentation included in the OpenDDS repository (``docs/cmake.md``).