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 |
---|---|---|
|
Enables verbose execution |
Quiet execution |
|
Prints a help (usage) message and exits |
N/A |
|
Prints version numbers of both TAO and OpenDDS |
N/A |
|
Set the version of IDL to use. |
4 |
|
List the versions of IDL at least partially supported. |
N/A |
|
Just check syntax of input files, exiting after parsing. |
Goes on to generate code |
|
Export macro used for generating C++ implementation code.
|
No export macro used |
|
Additional header to |
No additional include |
|
Pre-compiled header file to include in generated C++ files |
No pre-compiled header included |
|
Define a preprocessor macro |
N/A |
|
Add |
N/A |
|
Output directory where |
The current directory |
|
Enable OpenDDS Java Bindings for generated TypeSupport implementation classes |
No Java support |
|
Generates “Intermediate Type Language” descriptions of datatypes. These files are used by the Wireshark dissector or other external applications. |
Not generated |
|
Generates FACE (Future Airborne Capability Environment) Transport Services API |
Not generated |
|
Generate type support for converting data samples to/from V8 JavaScript objects
|
Not generated |
|
Generate type support for converting data samples to/from RapidJSON objects |
Not generated |
|
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 |
|
Generates IDL-to-C++ mapping for FACE |
Not generated |
|
Generates IDL-to-C++ mapping for Safety Profile |
Not generated |
|
Generates IDL-to-C++11 mapping |
Not generated |
|
Prefix the string s to #include directives meant to include headers generated by |
N/A |
|
Suppress generation of IDL TypeCodes when one of the |
IDL TypeCodes generated |
|
For IDL version 4, control the reaction to unknown annotations. The options are:
|
|
|
Don’t warn about |
Warnings are issued, use annotations to silence them |
|
Un-annotated types/modules are treated as nested. See Topic Types vs. Nested Types for details. |
Types are nested by default. |
|
Set the default XTypes extensibility.
Can be |
|
|
Do not set the type flags for enums. This flag is for simulating the behavior of previous versions of OpenDDS. |
|
|
Set the default XTypes auto member-id assignment strategy: sequential or hash – see @autoid(value) |
|
|
Set the default XTypes try-construct strategy: |
|
|
Use the pre-3.18 encoding of |
Use standard encoding |
|
Use the pre-3.24 struct and union member order for |
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
).