Merge pull request #1844 from jrw972/monterey

[ACE_TAO.git] / TAO / TAO_IDL / tao_idl.1

.\" Process this file with
.\" groff -man -Tascii tao_idl.1
.\"
.TH tao_idl 1 "DECEMBER 1998" "CORBA Tools" "User Manuals"
.SH NAME
tao_idl \- Compile IDL sources for use with the ACE ORB (TAO)
.SH SYNOPSIS
.B tao_idl
.BI [ OPTION... ]
.I filename
.SH DESCRIPTION
.B tao_idl
is a program that is used to compile
.I IDL
source code.  The IDL compiler generates 9 files from each .idl file,
the file names are obtained by taking the IDL basename and appending
C.h, C.inl, C.cpp, S.h, S.inl, S.cpp, S_T.h, S_T.inl, and S_T.cpp; the
client stubs are declared in the C.h file, the skeletons in the S.h
file. Please see the Options list on how to get different suffixes for
these files.

Both clients and servers should link against the object files for the stubs
and skeletons, this is needed to transparently support collocated objects.

The server skeleton can make use of different lookup strategies to match the
incoming operation with the correct operation at the servant.  Dynamic Hashing
and Perfect Hashing are the two different operation lookup strategies that are
currently supported in tao_idl.  By default, tao_idl tries to use Perfect
Hashing strategy.  If supported and available, gperf generates the lookup
methods for this strategy.
.SH OPTIONS
.TP
.B \-u
The compiler prints out the options that are given below and exits clean.
.TP
.B \-V
the compiler printouts its version and exits
.TP
.BI "\-Wb," "option_list"
pass options to the backend
.IP
.BI "skel_export_macro=" "macro_name"

The compiler will emit macro_name right after each class or extern
keyword in the generated skeleton code (S files,) 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.
.IP
.BI "skel_export_include=" "include_path"

The compiler will generate code to include include_path at the top of
the generated server header, this is usually a good place to define
the server side export macro.
.IP
.BI "stub_export_macro=" "macro_name"

The compiler will emit macro_name right after each class or extern
keyword in the generated stub code, 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.
.IP
.BI "stub_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.
.IP
.BI "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.
.IP
.BI "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.
.IP
.BI "pch_include=" "include_path"

The compiler will generate code to include include_path at the top of
all TAO IDL compiler generated files. This can be used with a
precompiled header mechanism, such as those provided by Borland
C++Builder or MSVC++.
.TP
.B \-E
only invoke the preprocessor
.TP
.BI "-Wp," "option_list"
pass options to the preprocessor
.TP
.BI "\-D" "macro_definition"
passed to the preprocessor
.TP
.BI "\-U" "macro_name"
passed to the preprocessor
.TP
.BI "\-I" "include_path"
passed to the preprocessor
.TP
.BI "\-A" "assertion"
passed to the preprocessor
.TP
.B \-Y
passed to the preprocessor
.TP
.B "\-H perfect_hash"
To specify the IDL compiler to generate skelton code that uses perfect
hashed operation lookup strategy, which is the default
strategy. Perfect hashing uses gperf program, to generate lookup methods.
.TP
.B "\-H dynamic_hash"
To specify the IDL compiler to generate skelton code that uses dynamic
hashed operation lookup strategy.
.TP
.B "\-H binary_search"
To specify the IDL compiler to generate skelton code that uses binary search
based operation lookup strategy.
.TP
.B "\-H linear_search"
To specify the IDL compiler to generate skelton code that uses linear search
based operation lookup strategy.
.TP
.B "\-in"
To generate #include statements with <>'s for the standard include
files (e.g. tao/corba.h) indicating them as non-changing files
.TP
.B "\-ic"
To generate #include statements with ""s for changing standard include
files (e.g. tao/corba.h).
.TP
.B \-g
To specify the path for the perfect hasing program (GPERF). Default is
$ACE_ROOT/bin/gperf or whatever the ACE_GPERF macro was defined to be
during compilation of TAO.
.TP
.B \-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
.B tao_idl
is called.
.TP
.B \-hc
Client's header file name ending. Default is "C.h".
.TP
.B \-hs
Server's header file name ending. Default is "S.h".
.TP
.B \-hT
Server's template header file name ending. Default is "S_T.h".
.TP
.B \-cs
Client stub's file name ending. Default is "C.cpp".
.TP
.B \-ci
Client inline file name ending. Default is "C.inl".
.TP
.B \-ss
Server skeleton file name ending. Default is "S.cpp".
.TP
.B \-sT
Server template skeleton file name ending. Default is "S_T.cpp".
.TP
.B \-si
Server inline skeleton file name ending. Default is "S.inl".
.TP
.B \-st
Server's template inline file name ending. Default is "S_T.inl".
.TP
.B \-t
Temporary directory to be used by the IDL compiler. Default : Resolve
ACE_DEFAULT_TEMP_DIR_ENV. If it is not defined, choose /tmp/.
.TP
.B \-Cw
Output a warning if two identifiers in the same scope differ in
spelling only by case (default for now).
.TP
.B \-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.
.TP
.B \-Gc
Generate stubs and skeletons using compiled marshaling.
.TP
.B \-Gi
Generate stubs and skeletons using interpretive marshaling (default for now).
.TP
.B \-Gl
.B For TAO Core developers only.
Generate locality constrained interface implementation. This flag is
not of general interests and should never be used by end-users.
.TP
.B \-Gp
Generated collocated stubs that use Thru_POA collocation strategy.
(default)
.TP
.B \-Gd
Generated collocated stubs that use Direct collocation strategy.
.TP
.B \-Gt
Generate optimized TypeCodes (unimplemented as yet).
.TP
.B \-Gv
Generate code that supports Object-By-Value.
.TP
.B \-GI
Generate templates files for the servant implementation.
.TP
.BI "\-GIh " "arg"
Servant implemenation header file name ending.
.TP
.BI "\-GIs " "arg"
Servant implemenation skeleton file name ending.
.TP
.BI "\-GIb " "arg"
Prefix to the implementation class names.
.TP
.BI "\-GIe " "arg"
Suffix to the implementation class names.
.TP
.BI "\-GIc " "arg"
Generate copy constructors in the servant implementation template
files.
.TP
.B \-Sa
Suppress generation of the
.I Any
operators
.TP
.B \-Sp
Suppress generation of collocated stubs that use Thru_POA collocation
strategy.
.TP
.B \-Sd
Suppress generation of collocated stubs that use Direct collocation
strategy. (default)
.TP
.B \-St
Suppress generation of the
.I TypeCodes
.SH BUGS
None.
.SH AUTHORS
.IP
Carlos O'Ryan <coryan@cs.wustl.edu>
.IP
Ossama Othman <othman@cs.wustl.edu>
performed man page conversion from original HTML source
.SH "SEE ALSO"
.BR gperf (1)