Chapter 3 Command-Line Arguments for rtiddsgen

Use this flag to obtain backward-compatibility when allocating optional members with DDS_Heap_malloc in C++.

Only applies if -language C, -language C++98, or -language C++11 is specified.

Generates code for only one data representation. This option may increase performance, because the generated code will not check the data representation during serialization/deserialization.

Only applies if -language C, -language C++98, or -language C++11 is specified.

Generates code for a specific endianness. This option may improve performance, because the generated code will not check the endianness during serialization/deserialization.

Only applies if -language C++11 is specified.

Generates code that maps all sequences to std::vector, even bounded sequences that would otherwise map to rti::core::bounded_sequence.

Alternatively, the @use_vector annotation can be applied to each sequence member.

Updates the auto-generated files, i.e, the typefiles and makefile/project files.

To see the valid options for <architecture> per language, run rtiddsgen with the -help option, or use the string "universal" (-autoGenFiles universal) to generate compatible publisher/subscriber code for all supported platforms. The universal architecture will not generate makefiles/project files.

This is a shortcut for:

-update typefiles -update makefiles -platform <architecture>

Only applies if -language C++98 is also specified.

Generates the types default constructor, copy constructor, copy assignment operator, and destructor. Using this option will also disable the generation of the following TypeSupport methods: create_data(_ex), delete_data(_ex), initialize_data(_ex), finalize_data(_ex), copy_data.

Creates the files indicated (typefiles, examplefiles, or makefiles) if they do not exist. For example:

rtiddsgen -language C++11 -create typefiles test.idl

If the files already exist, the files are not modified and a warning is printed.

There can be multiple -create options.

If you specify both -create and -update for the same file type, only -update will be applied.

If you use -create makefiles, the -platform <arch> option is required. For example:

rtiddsgen -language c -create makefiles -platform x64Darwin17clang9.0 test.idl

You can specify multiple input (e.g., .idl) files or folders. See Chapter 4 Generating Example Code for more information.

Converts the input type description file into IDL format. This option creates a new file with the same name as the input file and a .idl extension.

Converts the input type description file into XML format. This option creates a new file with the same name as the input file and a .xml extension.

Converts the input type description file into XSD format. This option creates a new file with the same name as the input file and a .xsd extension.

Defines preprocessor macros.

On Windows systems, enclose the argument in quotation marks:

-D "<name>[=<value>]"

Generates the output in the specified directory. By default, Code Generator will generate files in the directory where the input type-definition file is found.

Causes Code Generator not to check that the input XSD file is well-formed.

The use of this option is not recommended in general, as Code Generator may receive invalid inputs.

Defines the suffix of the macro that is used to export symbols when building Windows DLLs. The default macro is NDDS_USER_DLL_EXPORT. When this option is specified, the name of the macro is NDDS_USER_DLL_EXPORT_<Suffix>.

Enables use of the escape character '_' in IDL identifiers.

Normally, if you use an identifier that is an IDL keyword, you will see an error (for case-sensitive matches) or a warning (for case-insensitive ones). This option allows you to escape the IDL keywords with an underscore so that they can be used in the IDL.

Generates type files, example files, and a makefile.

This is a shortcut for:

-create typefiles -create examplefiles -create makefiles -platform <architecture>

To see the valid options for <architecture> per language, run rtiddsgen with the -help option, or use the string "universal" (-example universal) to generate compatible publisher/subscriber code for all supported platforms. The universal architecture will not generate makefiles/project files.

For Python, when generating examples, the only available platform is "universal". For example:

rtiddsgen -language Python -example -platform universal Hello.idl

Generates a custom example application using the specified custom publisher and subscriber templates, instead of the default example files. Place your custom templates in $NDDSHOME/resource/app/app_support/rtiddsgen/templates/example/<language>/<exampleTemplateDirectoryName>/. Name them publisher.vm and subscriber.vm; you can also add a QoS template (qosProfile.vm) file to your example template directory (if you don't, Code Generator will use the default one, $NDDSHOME/resource/app/app_support/rtiddsgen/templates/example/qosProfile.vm). You can base your templates on those that Connext provides in $NDDSHOME/resource/app/app_support/rtiddsgen/templates/example/<language>.

The -exampleTemplate option must be used in combination with one of the following command-line options:

• -create examplefiles
• -update examplefiles
• -example <architecture>

For example:

rtiddsgen -language C++11 -example x64Darwin17clang9.0 -exampleTemplate myCustomTemplate foo.idl

"myCustomTemplate" is your <exampleTemplateDirectoryName> in $NDDSHOME/resource/app/app_support/rtiddsgen/templates/example/<language>/<exampleTemplateDirectoryName>/.

To get a full list of the available custom templates in your Connext installation, use the

-showTemplates option.

For C++98, C++11, C#, Python, and Java, you can also use an advanced -exampleTemplate option included with Connext. See 4.3 Advanced Example.

The -exampleTemplate option is not supported in Ada.

Generates code for any included file in the inputs. For example:

rtiddsgen -language python Foo.idl -generateIncludeFiles

Imagine you have the following two files:

// File Bar.idl

struct Bar {

...

};

// File Foo.idl

#include "Bar.idl"

struct Foo {

Bar b;

};

This example will produce the following files:

• Foo.py
• Bar.py

Prints out the command-line options for rtiddsgen.

Adds to the list of directories to be searched for type-definition files (IDL or XML files). Note: A type-definition file in one format cannot include a file in another format.

Indicates that the input file is an IDL file, regardless of the file extension.

This command-line option is required when the input has one or more directories. See 4.1.4.2 Listing Directories for more information.

Indicates that the input file is an XML file, regardless of the file extension.

This command-line option is required when the input has one or more directories. See 4.1.4.2 Listing Directories for more information.

Indicates that the input file is an XSD file, regardless of the file extension.

This command-line option is required when the input has one or more directories. See 4.1.4.2 Listing Directories for more information.

A file containing IDL descriptions of your data types. If -inputIdl is not used, the file must have a '.idl' extension.

Specifies the language to use for the generated files.

Notes:

• Use -language C++98 or -language C++11 to select the Traditional C++ or Modern C++ API respectively. Note that C++98 and C++11 are the minimum C++ versions required by each API. Applications can use newer C++ standards.
• For Python, when generating examples, the only available platform is "universal". For example:

rtiddsgen -language Python -example -platform universal Hello.idl

Specifies the use of C++ namespaces, for traditional C++ only. For modern C++ and C#, it is implied—namespaces are always used.

Generates an obfuscated IDL file from the input file. Note that even if the input type is XML, this option generates an obfuscated IDL file.

Level of optimization of the code:

• 0: No optimization.
• 1: The compiler generates extra code for typedefs but optimizes its use. If a type that is used is a typedef that can be resolved to a primitive, enum, or aggregated type (struct, union, or value type), the generated code will invoke the code of the most basic type to which the typedef can be resolved. This level can be used if the generated code is not expected to be modified. This is the only optimization level supported for Java and C# languages.
• 2: (Default) This optimization level applies only to C, C++, C++11 and higher, and Ada languages. With this optimization level, rtiddsgen optimizes the serialization/deserialization of structures and valuetypes by using more aggressive techniques. These techniques include inline expansion of nested types and serialization/deserialization of a set of consecutive members with a single copy function invocation (memcpy) when the memory layout (C, C++ structure layout) is the same as the wire layout (XCDR). See Chapter 7 Optimizing the Code Generation Process for more information.

2 is the default for C, C++, C++11 and higher, and Ada languages (but you can change it to 0 or 1). 1 is always used for Java and C# languages, and you cannot change it.

Specifies the root package into which generated classes will be placed. It applies to Java only. If the type-definition file contains module declarations, those modules will be considered subpackages of the package specified here.

Required if -create makefiles or -update makefiles is used.

To see the valid options for <architecture> per language, run rtiddsgen with the -help option, or use the string "universal" (-platform universal) to generate compatible publisher/subscriber code for all supported platforms. The universal architecture will not generate makefiles/project files.

For Python, when generating examples, the only available platform is "universal". For example:

rtiddsgen -language Python -example -platform universal Hello.idl

Disables the preprocessor.

Code Generator supports the standard preprocessor directives defined by the IDL specification, such as #if, #endif, #include, and #define.

To support these directives, Code Generator calls an external C preprocessor before parsing the IDL file. On Windows systems, the preprocessor is ‘cl.exe.’ On other architectures, the preprocessor is ‘cpp.’ You can change the default preprocessor with the –ppPath option. If you do not want to run the preprocessor, use the –ppDisable option.

The argument -ppDisable tells the code generator not to attempt to invoke the C preprocessor on the IDL file prior to generating code. In some cases, the IDL file contains no preprocessor directives, so no preprocessing is necessary. Therefore, you may want to use the -ppDisable option to tell Code Generator to skip calling the preprocessor. However, if the preprocessor executable is already on your system path (on Windows systems, it will be on your path if you've run the Visual Studio "vcvars" batch file that is appropriate for your architecture), you don't need to use -ppDisable.

In summary, -ppDisable is a useful, quick remedy for simple examples (including HelloWorld examples) for which the IDL is simple and does not need Code Generator to invoke the preprocessor. The longterm recommendation, however, is to have the preprocessor in your path (or use the -ppOption). Linux architectures often already have the preprocessor in the path; Windows architectures may require you to run a "vcvars" batch file as described at the beginning of this chapter to put the preprocessor in your path.

Specifies a preprocessor option. This option can be used multiple times to provide the command-line options for the specified preprocessor. See -ppPath <path to preprocessor>.

Specifies the preprocessor. If you only specify the name of an executable (not a complete path to that executable), the executable must be found in your Path. The default value is cpp for non-Windows architectures and cl.exe for Windows architectures.

If you use -ppPath to provide the full path and filename for cl.exe or the cpp preprocessor, you must also use -ppOption <option> to set the following preprocessor options:

If you use a non-default path for cl.exe, you also need to set:

-ppOption /nologo -ppOption /C -ppOption /E -ppOption /X

If you use a non-default path for cpp, you also need to set:

 -ppOption -C

Uses the fully qualified name for enumerator values including the enum value.

Deprecated option. Instead, use -update <typefiles| examplefiles|makefiles> for the proper files (typefiles, examplefiles, makefiles).

This option is maintained for backwards compatibility. It allows Code Generator to overwrite any existing generated files.

If it is not present and existing files are found, Code Generator will print a warning but will not overwrite them.

Sets the size assigned to unbounded sequences. The default value is 100 elements.

Generates makefiles that compile with the Connext shared libraries (by default, the makefile will link with the static libraries)

Prints and generates an XML file containing a list of the available example templates in your Connext installation, organized per language. When you use the -exampleTemplate option, you can specify one of these example templates. Code Generator will then generate the example you specified instead of the default one.

Defines the mapping for a specific standard. This flag is only supported in C++11.

Use the option DDS_PSM_Cxx for the default mapping used in versions before 7.2.0.

Use the option IDL4_CPP for the new IDL4 to CPP Language Mapping defined by the OMG in 2023.

The most notable changes in the IDL4-CPP mapping are:

• IDL structs map to C++ structs with public fields, instead of classes with getters and setters
• IDL unions still map to classes with getters and setters with the following additions:
  • For members selected by multiple labels, a setter receiving the discriminator value as a second argument is also generated
  • A method called _default() that sets the union to its default discriminator is generated
• string and wstring constants map to std::string_view and std::wstring_view for platforms that support C++17

Enforces compliance with the OMG 'Extensible and Dynamic Topic Types for DDS' specification, version 1.3 by turning informational (INFO) messages into errors. (Informational messages are described in -verbosity [1-3].)

Currently in this release, by default, Code Generator will report an informational (INFO) message for keyed derived structures when running rtiddsgen, but still generate code:

INFO com.rti.ndds.nddsgen.antlr.annotation.AnnotationApplier 

struct/valuetype derived from a struct/valuetype should not contain @key fields. 

This is not compliant with the XTypes specification. You can make this message 

an error by using the -strict flag

If you want Code Generator to enforce the specification, use the -strict option. This option will report an error when there are keyed derived structures, and not generate code.

See the RTI Code Generator Release Notes or the Migration Guide on the RTI Community Portal (https://community.rti.com/documentation) for enforcement details that might occur in future releases.

Sets the size assigned to unbounded strings, not counting a terminating NULL character. The default value is 255 bytes.

Assigns a suffix to the name of the implicit sequence defined for IDL types. The option is compatible with languages C, C++, C#, and Java. By default, the suffix is 'Seq'. For example, given the type 'Foo', the name of the sequence would be 'FooSeq'.

Displays the maximum serialized size, minimum serialized size, and maximum key serialized size of all the complex types in an IDL.

If Code Generator cannot compute the type sizes, it will display the following:

• If there is a recursive type, Code Generator will display Undefined (Recursive Type).
• If there is a type that is unresolved because you are using @resolve-name false, Code Generator will display Undefined (Unresolved Member).
• If the type is bigger than the maximum serialized size, Code Generator will display Error (Over Max Serialized Size).

NOTE: Using this option may reduce Code Generator performance. We recommend you disable the flag if you just want to generate code and you don't want or need type information.

Cancels any previous definition of <name>.

Generates code that supports unbounded sequences and strings. When the option is used, the command-line options -sequenceSize and -stringSize are ignored.

This option also affects the way unbounded sequences are deserialized. When a sequence is being received into a sample from the DataReader's cache, the old memory for the sequence will be deallocated and memory of sufficient size to hold the deserialized data will be allocated. When initially constructed, sequences will not preallocate any elements having a maximum of zero elements.

For more information on using the -unboundedSupport option, including some required QoS settings, see:

• Sequences, in the RTI Connext Core Libraries User's Manual
• Strings and Wide Strings, in the RTI Connext Core Libraries User's Manual
• Sample and Instance Memory Management, in the RTI Connext Core Libraries User's Manual

Creates the files indicated if they do not exist. For example:

rtiddsgen -language C++11 -update typefiles test.idl

If the files already exist, -update overwrites the files without printing a warning.

There can be multiple -update options.

If you specify both -create and -update for the same file type, only the -update will be applied.

If you use -update makefiles, the -platform <arch> option is required. For example:

rtiddsgen -language c -update makefiles -platform x64Darwin17clang9.0 test.idl

You can specify multiple input (e.g., .idl) files or folders. See Chapter 4 Generating Example Code for more information.

This option should be used when compatibility with 5.2.3 and earlier General Access Releases (GARs) is required when using keyed mutable types (related to RTI Issue IDs CODEGENII-501 and CODEGENII-693).

This option should be used when compatibility with 5.2.6 is required when using keyed mutable types (related to RTI Issue ID CODEGENII-693).

Use 'std::string' instead of 'char *' when generating code for IDL strings when the language option is C++.

Using this option will automatically enable constructor generation. Therefore you can use this option with or without -constructor and achieve the same result.

Defines a user variable that can be used in the templates as $userVarList.name or $userVarList.name.equals(value). The variables defined with this option are case sensitive.

Sets the Code Generator verbosity:

1: Exceptions

2: Exceptions and warnings

3: Exceptions, warnings and information (Default)

Displays the version of Code Generator being used, such as 2.x.y, as well as the version of the templates being used (xxxx-xxxx-xxxx).

Only applies if -language C++98 is also specified.

Generates a virtual destructor for the generated types in C++. Using this option will automatically enable the -constructor option.

Note that using this option will affect filtering performance when using ContentFilteredTopics or QueryConditions.