opendds_idl#

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 Processing the IDL for an overview of the default usage pattern.

The OpenDDS IDL compiler is invoked using the opendds_idl executable, located in 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,

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 Command Line Options#

--help, -h#

Prints a help message and exits.

-v#

Enables verbose/debug logging.

--version, -V#

Prints version numbers of both TAO and OpenDDS.

--idl-version VERSION#

Set the version of the IDL specification to use. The default is 4.

--list-idl-versions#

List the versions of IDL at least partially supported and exits.

--syntax-only#

Just check syntax of input files and exit without generating any code.

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

-Wb,export_include=FILE#

Add an additional header FILE to #include in generated code that has the export macro.

-Wb,pch_include=FILE#

Include a pre-compiled header FILE in generated C++ files.

-Dname[=value]#

Define a preprocessor macro named name optionally with value value for IDL.

-Idir#

Adds dir to the preprocessor include path for IDL.

-o OUTPUT_PATH#

Output directory where generated files are put. By default this is the current working directory.

-Wb,java#

Generate Java Bindings for generated TypeSupport implementation classes. See Java Bindings for more information.

-Gitl#

Generate “Intermediate Type Language” descriptions of topic types. These files are used by the Wireshark dissector or other external applications.

-GfaceTS#

Generate FACE (Future Airborne Capability Environment) Transport Services API. See Safety Profile for more information.

-Gv8#

Generate type support for converting data samples to/from V8 JavaScript objects -Wb,v8 is an alias for this.

-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 Dynamic Language Binding for more information.

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

-Lface#

Generates IDL-to-C++ mapping for FACE. See Safety Profile for more information.

-Lspcpp#

Generates IDL-to-C++ mapping for Safety Profile.

-Lc++11#

Generates IDL-to-C++11 mapping.

-Wb,tao_include_prefix=S#

Prefix the string S to #include directives meant to include headers generated by tao_idl.

-St#

Suppress generation of IDL TypeCodes when one of the -L options are present.

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

--no-dcps-data-type-warnings#

Don’t warn about #pragma DCPS_DATA_TYPE. See Identifying Topic Types for more information.

--[no-]default-nested#

Un-annotated types/modules are treated as nested. By default all types are nested by default See Topic Types vs. Nested Types for details.

--default-extensibility EXT#

Set the default XTypes extensibility. EXT can be:

  • final

  • appendable (default)

  • mutable

--default-autoid VALUE#

Set the default XTypes auto member-id assignment strategy. VALUE can be sequential (the default) or hash.

--default-try-construct VALUE#

Set the default XTypes try-construct strategy. VALUE can be discard (the default), use-default, or trim.

--old-typeobject-encoding#

New in version 3.18.

Use the pre-3.18 encoding of TypeObjects when deriving TypeIdentifiers.

--default-enum-extensibility-zero#

New in version 3.22.

Do not set the type flags for enums. This flag is for simulating the behavior of OpenDDS before 3.22.

--old-typeobject-member-order#

New in version 3.24.

Use the pre-3.24 struct and union member order for TypeObjects, which is ordered by member id instead of declared order. See 3.24.0 news entry for more info.

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.

Using the IDL-to-C++11 Mapping#

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 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 <other options> 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 Defining Data Types with IDL and IDL Annotations

  • #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 Using OpenDDS in a CMake Project.