TAO IDL compiler User's Guide

Scope

This document describes the options and features of TAO IDL compiler. It is not a reference manual or tutorial on OMG IDL. For more information on OMG IDL see the online CORBA specification and the Advanced CORBA Programming with C++ book.

Generated Files

The IDL compiler generates 9 files from each .idl file. The file names are obtained by taking the IDL basename and appending the following suffixes (see the list of TAO's IDL compiler options on how to get different suffixes for these files:)

Client stubs -- *C.h, *C.i, and *C.cpp
Server skeletons -- *S.h, *S.i, and *S.cpp
Server skeleton templates -- *S_T.h, S_T.i, and *S_T.cpp

TAO's IDL compiler creates separate *.i and *S_T.* files to improve the performance of the generated code. Fortunately, you only need to #include the client stubs declared in the *C.h file and the skeletons in the *S.h file in your code.

Operation Demuxing Strategies

The server skeleton can use different demuxing strategies to match the incoming operation with the correct operation at the servant. TAO's IDL compiler supports perfect hashing, binary search, and dynamic hashing demuxing strategies. By default, TAO's IDL compiler tries to generate perfect hash functions, which is generally the most efficient and predictable operation demuxing technique. To generate perfect hash functions, TAO's IDL compiler uses gperf , which is a general-purpose perfect hash function generator.

To configure TAO's IDL compiler to support perfect hashing please do the following:

Enable ACE_HAS_GPERF when building ACE and TAO. This macro has been defined for the platforms where gperf has been tested, which includes most platforms that ACE runs on.
Build the gperf in $ACE_ROOT/apps/gperf. This build also leaves a copy/link of the gperf program at the $ACE_ROOT/bin directory.
Set the environment variable $ACE_ROOT appropriately or add $ACE_ROOT/bin to your search path.
Use the -g option for the TAO IDL compiler or set your search path accordingly to install gperf in a directory other than $ACE_ROOT/bin.

Note that if you can't use perfect hashing for some reason the next best operation demuxing strategy is binary search, which can be configured using TAO's IDL compiler options.

TAO's IDL Compiler Options

TAO's IDL compiler invokes your C (or C++) preprocessor to resolve included IDL files. It receives the common options for preprocessors (such as -D or -I). It also receives other options that are specific to it.

Option Description

-u The compiler prints out the options that are given below and exits clean

-V The compiler printouts its version and exits

-Wb,option_list Pass options to the backend.

export_macro=macro_name The compiler will emit macro_name right after each class or extern keyword, this is needed for Windows/NT that requires special directives to export symbols from DLLs, usually the definition is just a space on unix platforms.

export_include=include_path The compiler will generate code to include include_path at the top of the client header, this is usually a good place to define the export macro.

-E Only invoke the preprocessor

-Wp,option_list Pass options to the preprocessor.

-Dmacro_definition It is passed to the preprocessor

-Umacro_name It is passed to the preprocessor

-Iinclude_path It is passed to the preprocessor

-Aassertion It is passed to the preprocessor

-Y It is passed to the preprocessor

-H perfect_hash To specify the IDL compiler to generate skelton code that uses perfect hashed operation demuxing strategy, which is the default strategy. Perfect hashing uses gperf program, to generate demuxing methods.

-H dynamic_hash To specify the IDL compiler to generate skelton code that uses dynamic hashed operation demuxing strategy.

-H binary_search To specify the IDL compiler to generate skelton code that uses binary search based operation demuxing strategy.

-H linear_search To specify the IDL compiler to generate skelton code that uses linear search based operation demuxing strategy. Note that this option is for testing purposes only and should not be used for production code since it's inefficient.

-in To generate #include statements with <>'s for the standard include files (e.g. tao/corba.h) indicating them as non-changing files

-ic To generate #include statements with ""s for changing standard include files (e.g. tao/corba.h).

-g To specify the path for the perfect hasing program (GPERF). Default is $ACE_ROOT/bin/gperf.

-o To specify the output directory to IDL compiler as to where all the IDL-compiler-generated files are to be put. By default, all the files are put in the current directory from where is called.

-hc Client's header file name ending. Default is "C.h".

-hs Server's header file name ending. Default is "S.h".

-hT Server's template header file name ending. Default is "S_T.h".

-cs Client stub's file name ending. Default is "C.cpp".

-ci Client inline file name ending. Default is "C.i".

-ss Server skeleton file name ending. Default is "S.cpp".

-sT Server template skeleton file name ending. Default is "S_T.cpp".

-si Server inline skeleton file name ending. Default is "S.i".

-st Server's template inline file name ending. Default is "S_T.i".

-t Temporary directory to be used by the IDL compiler. Default : Resolve ACE_DEFAULT_TEMP_DIR_ENV. If it is not defined, choose /tmp/.

-Cw Output a warning if two identifiers in the same scope differ in spelling only by case (default for now).

-Ce Output an error if two indentifiers in the same scope differ in spelling only by case. Default output is warning (for now). Since there is at least one OMG IDL file (sfp.idl, part of the AVStreams specification) that is inconsistent with its own spelling rule, we have made a warning the default output until the issue is resolved.

-Gc Generate stubs and skeletons using compiled marshaling

-Gi Generate stubs and skeletons using interpretive marshaling (default for now)

-Ge flag If the value of the flag is 0, tao_idl will generate code that will use native C++ exceptions. If the value of the flag is 1, tao_idl will generate code that will use environment variable for passing exceptions

-Gt Generate optimized TypeCodes (unimplemented as yet)

-Gv Generate code that suppports Object-By-Value

-GI Generate templates files for the servant implementation

-GIh arg Servant implemenation header file name ending

-GIs arg Servant implemenation skeleton file name ending

-GIb arg Prefix to the implementation class names

-GIe arg Suffix to the implementation class names

-GIc arg Generate copy constructors in the servant implementation template files

-Sa Suppress generation of the Any operators

-St Suppress generation of the TypeCodes

Option	Description
`-u`	The compiler prints out the options that are given below and exits clean
`-V`	The compiler printouts its version and exits
`-Wb,`option_list	Pass options to the backend.
	`export_macro=`macro_name	The compiler will emit macro_name right after each `class` or `extern` keyword, this is needed for Windows/NT that requires special directives to export symbols from DLLs, usually the definition is just a space on unix platforms.
	`export_include=`include_path	The compiler will generate code to include include_path at the top of the client header, this is usually a good place to define the export macro.
`-E`	Only invoke the preprocessor
`-Wp,`option_list	Pass options to the preprocessor.
`-D`macro_definition	It is passed to the preprocessor
`-U`macro_name	It is passed to the preprocessor
`-I`include_path	It is passed to the preprocessor
`-A`assertion	It is passed to the preprocessor
`-Y`	It is passed to the preprocessor
`-H perfect_hash`	To specify the IDL compiler to generate skelton code that uses perfect hashed operation demuxing strategy, which is the default strategy. Perfect hashing uses gperf program, to generate demuxing methods.
`-H dynamic_hash`	To specify the IDL compiler to generate skelton code that uses dynamic hashed operation demuxing strategy.
`-H binary_search`	To specify the IDL compiler to generate skelton code that uses binary search based operation demuxing strategy.
`-H linear_search`	To specify the IDL compiler to generate skelton code that uses linear search based operation demuxing strategy. Note that this option is for testing purposes only and should not be used for production code since it's inefficient.
`-in`	To generate #include statements with <>'s for the standard include files (e.g. tao/corba.h) indicating them as non-changing files
`-ic`	To generate #include statements with ""s for changing standard include files (e.g. tao/corba.h).
`-g`	To specify the path for the perfect hasing program (GPERF). Default is $ACE_ROOT/bin/gperf.
`-o`	To specify the output directory to IDL compiler as to where all the IDL-compiler-generated files are to be put. By default, all the files are put in the current directory from where is called.
`-hc`	Client's header file name ending. Default is "C.h".
`-hs`	Server's header file name ending. Default is "S.h".
`-hT`	Server's template header file name ending. Default is "S_T.h".
`-cs`	Client stub's file name ending. Default is "C.cpp".
`-ci`	Client inline file name ending. Default is "C.i".
`-ss`	Server skeleton file name ending. Default is "S.cpp".
`-sT`	Server template skeleton file name ending. Default is "S_T.cpp".
`-si`	Server inline skeleton file name ending. Default is "S.i".
`-st`	Server's template inline file name ending. Default is "S_T.i".
`-t`	Temporary directory to be used by the IDL compiler. Default : Resolve ACE_DEFAULT_TEMP_DIR_ENV. If it is not defined, choose /tmp/.
`-Cw`	Output a warning if two identifiers in the same scope differ in spelling only by case (default for now).
`-Ce`	Output an error if two indentifiers in the same scope differ in spelling only by case. Default output is warning (for now).	Since there is at least one OMG IDL file (sfp.idl, part of the AVStreams specification) that is inconsistent with its own spelling rule, we have made a warning the default output until the issue is resolved.
`-Gc`	Generate stubs and skeletons using compiled marshaling
`-Gi`	Generate stubs and skeletons using interpretive marshaling (default for now)
`-Ge` flag	If the value of the flag is 0, tao_idl will generate code that will use native C++ exceptions. If the value of the flag is 1, tao_idl will generate code that will use environment variable for passing exceptions
`-Gt`	Generate optimized TypeCodes (unimplemented as yet)
`-Gv`	Generate code that suppports Object-By-Value
-`GI`	Generate templates files for the servant implementation
`-GIh` arg	Servant implemenation header file name ending
`-GIs` arg	Servant implemenation skeleton file name ending
`-GIb` arg	Prefix to the implementation class names
`-GIe` arg	Suffix to the implementation class names
`-GIc` arg	Generate copy constructors in the servant implementation template files
`-Sa`	Suppress generation of the Any operators
`-St`	Suppress generation of the TypeCodes

Back to the TAO documentation.