Chapter 3 Command-Line Arguments for rtiddsgen
On Windows systems: Before running rtiddsgen, run the "vcvars" batch file that is appropriate for your architecture in the same command prompt that you will use to run rtiddsgen. For example: vcvarsall.bat x86. The location of the "vcvars" batch file varies depending on your version of Visual Studio. Consult the Microsoft Visual Studio documentation for the exact location and parameters for your installation. Alternatively, run rtiddsgen from the Visual Studio Command Prompt under the Visual Studio Tools folder. Or, use the command-line argument -ppDisable. See -ppDisable in Table 3.1 Options for rtiddsgen.
If you are generating code for Connext, the options are:
rtiddsgen [-help]
[-allocateWithMalloc]
[ -allowedDataRepresentation <xcdr1, xcdr2>]
[ -allowedEndian <bigEndian, littleEndian>]
[-alwaysUseStdVector]
[-autoGenFiles <architecture>]
[-constructor]
[-create <typefiles| examplefiles|makefiles>]
[-convertToIdl | -convertToXML | -convertToXsd]
[-D <name>[=<value>]]
[-d <outdir>]
[-disableXSDValidation]
[-dllExportMacroSuffix <suffix>]
[-enableEscapeChar]
[-example <architecture>]
[-exampleTemplate]
[-generateIncludeFiles]
[-I <directory>]
[[-inputIdl] <IDLInputFile.idl> | [-inputXml] <XMLInputFile.xml>
|[-inputXsd <IDLInputFile.idl>]]
[-language <Ada|C|C++98|C++11|C#|Java|Python>]
[-namespace]
[-obfuscate]
[-optimization <level>]
[-package <packagePrefix>]
[-platform <architecture>]
[-ppDisable]
[-ppPath <path to preprocessor>]
[-ppOption <option>]
[-qualifiedEnumerator]
[-replace]
[-sequenceSize <unbounded sequences size>]
[-sharedLib]
[-showTemplates]
[-standard <DDS_PSM_Cxx, IDL4_CPP>]
[-strict]
[-stringSize <unbounded strings size>]
[-typeSequenceSuffix <suffix>]
[-typeSizes]
[-U <name>]
[-unboundedSupport]
[-update <typefiles| examplefiles|makefiles>]
[-use52Keyhash]
[-use526Keyhash]
[-useStdString]
[-V <name< [=<value>]]
[-verbosity [1-3]]
[-version]
[-virtualDestructor]
Table 3.1 Options for rtiddsgen describes the options.
Note: Before using a makefile created by Code Generator to compile an application, make sure the ${NDDSHOME} environment variable is set as described in Set Up Environment Variables (rtisetenv), in the RTI Connext Getting Started Guide.
Option |
Description |
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: |
|
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:
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 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:
|
|
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:
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:
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:
|
|
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:
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: |
|
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. |
|
A file containing XML descriptions of your data types. If -inputXml is not used, the file must have an .xml extension. |