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#

The following table summarizes the options supported by opendds_idl.

Table opendds_idl Command Line Options

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

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

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 Topic Types vs. Nested Types for details.

Types are nested by default.

--default-extensibility

Set the default XTypes extensibility. Can be final, appendable or mutable. See 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 @autoid(value)

sequential

--default-try-construct VAL

Set the default XTypes try-construct strategy: discard, use-default, or trim – see Customizing XTypes per-member

discard

--old-typeobject-encoding

Use the pre-3.18 encoding of TypeObjects when deriving TypeIdentifiers

Use standard encoding

--old-typeobject-member-order

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.

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.

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

  • #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).