diff options
Diffstat (limited to 'TAO/docs/compiler.html')
| -rw-r--r-- | TAO/docs/compiler.html | 545 |
1 files changed, 0 insertions, 545 deletions
diff --git a/TAO/docs/compiler.html b/TAO/docs/compiler.html deleted file mode 100644 index 8b9b7fdf1fb..00000000000 --- a/TAO/docs/compiler.html +++ /dev/null @@ -1,545 +0,0 @@ -<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<meta name="GENERATOR" content="Mozilla/4.5 [en] (X11; I; SunOS 5.5.1 sun4u) [Netscape]"> -<title>TAO IDL compiler User's Guide</title> -<!-- $Id$ --> -</head> -<body text="#000000" bgcolor="#FFFFFF" link="#0000FF" vlink="#CC0000"> - -<hr> -<h3> -TAO IDL compiler User's Guide</h3> - -<h2> Scope</h2> 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 <A -HREF="http://www.omg.org/library/c2indx.html">online CORBA -specification</A> and the <A -HREF="http://www.triodia.com/staff/michi-henning.html">Advanced CORBA -Programming with C++</A> book. <P> - -<HR><P> -<h3>Generated Files</h3> - -The IDL compiler generates 9 files from each <tt>.idl</tt> file. The -file names are obtained by taking the IDL <EM>basename</EM> and -appending the following suffixes (see the list of TAO's IDL compiler -<A HREF="#options">options</A> on how to get different suffixes for -these files:) <P> - -<UL> - <LI> <EM>Client stubs</EM> -- <tt>*C.h</tt>, <tt>*C.i</tt>, and <tt>*C.cpp</tt> - <LI> <EM>Server skeletons</EM> -- <tt>*S.h</tt>, <tt>*S.i</tt>, and - <tt>*S.cpp</tt> - <LI> <EM>Server skeleton templates </EM> -- <tt>*S_T.h</tt>, <tt>S_T.i</tt>, - and <tt>*S_T.cpp</tt> -</UL> - -TAO's IDL compiler creates separate <TT>*.i</TT> and <TT>*S_T.*</TT> -files to improve the performance of the generated code. Fortunately, -you only need to <CODE>#include</CODE> the client stubs declared in -the <tt>*C.h</tt> file and the skeletons in the <tt>*S.h</tt> file in -your code. <P> - -<HR><P> -<a name="idl_env"><h3>Environment Variables</h3></a> -TAO_IDL looks for two environment variables <code>CPP_LOCATION</code> -and <code>TAO_IDL_DEFAULT_CPP_FLAGS</code>. TAO_IDL doesn't -implements its own preprocessor and it borrows the preprocessor of -the compiler of your choice to perform the preprocessing work. -On most platform TAO's makefiles can locate the compiler -automatically. However, on NT and some other situation (like cross -compiling,) you need to instruct which specific compiler to use. -<code>CPP_LOCATION</code> allows you to achieve this. It holds the -program name of the compiler that TAO_IDL uses. This should be a full -pathname if the compiler is not within your <code>$PATH</code>. - -TAO_IDL also defines a set of default command line options passed to -the preprocessor depending on which platform TAO_IDL is compiled. The -environment variable <CODE>TAO_IDL_DEFAULT_CPP_FLAGS</CODE> allows you -to alter the command line optiona passed to the preprocessor. You can -use it to alter the default options for the preprocessor and specify -things like include directories and how the preprocessor is invoked. -Two flags that won't get overwritten by the environment variable are -<code>-DIDL</code> and <code>-I.</code>. They are always passed to -the preprocessor. - -If your IDLs need to include <code><orb.idl></code>, then you need to -define either/both <code>ACE_ROOT</code> or/and <code>TAO_ROOT</code>. If you -already have <CODE>ACE_ROOT</CODE> defined, TAO_IDL can figure -<CODE>TAO_ROOT</CODE> out if your ACE/TAO was installed using default directory -structure, otherwise, you'll need to define <code>TAO_ROOT</code>. - -<HR><P> -<h3>Operation Demuxing Strategies</h3> - -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 <A -HREF="http://www.cs.wustl.edu/~schmidt/COOTS-99.ps.gz">efficient and -predictable operation demuxing technique</A>. To generate perfect -hash functions, TAO's IDL compiler uses <a -href="http://www.cs.wustl.edu/~schmidt/gperf.ps.gz">gperf </a>, which -is a general-purpose perfect hash function generator. <P> - -To configure TAO's IDL compiler to support perfect hashing please do -the following: - -<ul> - <LI>Enable <CODE>ACE_HAS_GPERF</CODE> when building ACE and TAO. - This macro has been defined for the platforms where <CODE>gperf</CODE> - has been tested, which includes most <A - HREF="http://www.cs.wustl.edu/~schmidt/ACE-versions-i.html">platforms</A> - that ACE runs on. <P> - - <li>Build the <CODE>gperf</CODE> in $ACE_ROOT/apps/gperf. This build - also leaves a copy/link of the gperf program at the $ACE_ROOT/bin - directory.<P> - - <li>Set the environment variable $ACE_ROOT appropriately or add - $ACE_ROOT/bin to your search path. <P> - - <li>Use the <CODE>-g</CODE> option for the TAO IDL compiler or set - your search path accordingly to install <CODE>gperf</CODE> in a - directory other than $ACE_ROOT/bin. -</ul> - -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 <A HREF="#options">options</A>.<P> - -<hr><p> -<h3><a name="collocation-stubs">Collocation Strategies</a></h3> - -TAO_IDL can generate collocated stubs using two different collocation -strategies. It also allows you to supress/enable the generation of -the stubs of a particular strategy. To gain great flexibility at -run-time, you can gereate stubs for both collocation strategies -(using both '<a href="#Gp"><code>-Gp</code></a>' and '<a -href="#Gd"><code>-Gd</code></a>' flags at the same time) and defer the -determination of collocation strategy until run-time. On the other -hand, if you want to minimize the footprint of your program, you might -want to pre-determine the collocation strategy you want and only -generate the right collocated stubs (or not generating any at all using -both '<a href="#Sp"><code>-Sp</code></a>' and '<a -href="#Sd"><code>-Sd</code></a>' flags at the same time if -it's a pure client.) See our <a -href="http://www.cs.wustl.edu/~schmidt/C++-report-col18.ps.gz">collocation -paper</a> for a detail discussion on the collocation support in -TAO.<p> - - -<HR><P> -<h3><A NAME="options">TAO's IDL Compiler Options</A></h3> - -TAO's IDL compiler invokes your <tt>C</tt> (or <tt>C++</tt>) -preprocessor to resolve included IDL files. It receives the common -options for preprocessors (such as <tt>-D</tt> or <tt>-I</tt>). It -also receives other options that are specific to it. <P> - -<table BORDER=2 CELLSPACING=2 CELLPADDING=0 > - <tr> - <th>Option</th> - <th>Description</th> - <th>Remark</th> - </tr> - <tr><a NAME="u"> - <td><tt>-u</tt></td> - - <td>The compiler prints out the options that are given below and exits - clean </td> - <td> </td> - </tr> - - <tr> <a NAME="V"> - <td><tt>-V</tt></td> - - <td>The compiler printouts its version and exits</td> - <td> </td> - </tr> - - <tr><a name="Wb"> - <td><tt>-Wb,</tt><i>option_list</i></EM</TD></td> - - <td>Pass options to the TAO IDL compiler backend.</td> - <td> </td> - </tr> - - <tr><a name="export_macro"> - <td></td> - - <td><tt>export_macro=</tt><i>macro_name</i></td> - - <td>The compiler will emit <i>macro_name</i> right after each <tt>class</tt> - or <tt>extern</tt> 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. </td> - </tr> - - <tr><a name="export_include"> - <td></td> - - <td><tt>export_include=</tt><i>include_path</i></td> - - <td>The compiler will generate code to include <i>include_path</i> at the - top of the client header, this is usually a good place to define the export - macro.</td> - </tr> - - <tr><a name="pch_include"> - <td></td> - - <td><tt>pch_include=</tt><i>include_path</i></td> - - <td>The compiler will generate code to include <i>include_path</i> 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++.</td> - </tr> - - <tr><a name="E"> - <td><tt>-E</tt></td> - - <td>Only invoke the preprocessor</td> - <td> </td> - </tr> - - <tr><a name="Wp"> - <td><tt>-Wp,</tt><i>option_list</i></EM</TD></td> - - <td>Pass options to the preprocessor.</td> - <td> </td> - </tr> - - <tr><a name="D"> - <td><tt>-D</tt><i>macro_definition</i></td> - - <td>It is passed to the preprocessor</td> - <td> </td> - </tr> - - <tr><a name="U"> - <td><tt>-U</tt><i>macro_name</i></td> - - <td>It is passed to the preprocessor</td> - <td> </td> - </tr> - - <tr><a name="I"> - <td><tt>-I</tt><i>include_path</i></td> - - <td>It is passed to the preprocessor</td> - <td> </td> - </tr> - - <tr><a name="A"> - <td><tt>-A</tt><i>assertion</i></td> - - <td>It is passed to the preprocessor</td> - <td> </td> - </tr> - - <tr><a name="Y"> - <td><tt>-Y</tt></td> - - <td>It is passed to the preprocessor</td> - <td> </td> - </tr> - - <tr><a name="H perfect_hash"> - <td><tt>-H perfect_hash</tt></td> - - <td>To specify the IDL compiler to generate skelton code that uses perfect - hashed operation demuxing strategy, which is the default strategy. Perfect - hashing uses <a href="http://www.cs.wustl.edu/~schmidt/gperf.ps.gz">gperf - </a>program, - to generate demuxing methods. </td> - <td> </td> - </tr> - - <tr><a name="H dynamic_hash"> - <td><tt>-H dynamic_hash</tt></td> - - <td>To specify the IDL compiler to generate skelton code that uses dynamic - hashed operation demuxing strategy. </td> - <td> </td> - </tr> - - <tr><a name="H binary_search"> - <td><tt>-H binary_search</tt></td> - - <td>To specify the IDL compiler to generate skelton code that uses binary - search based operation demuxing strategy. </td> - <td> </td> - </tr> - - <tr><a name="H linear_search"> - <td><tt>-H linear_search</tt></td> - - <td>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.</td> - <td> </td> - </tr> - - - <tr><a name="in"> - <TD><TT>-in</TT></TD> - <TD> To generate #include statements with <>'s for the standard - include files (e.g. tao/corba.h) indicating them as non-changing - files</TD> - <td> </td> - </TR> - - - <TR><A NAME="ic"> - <TD><TT>-ic</TT></TD> - <TD> To generate #include statements with ""s for changing - standard include files (e.g. tao/corba.h). </TD> - <td> </td> - </TR> - - <tr><a name="g"> - <td><tt>-g</tt></td> - - <td>To specify the path for the perfect hasing program (GPERF). Default - is $ACE_ROOT/bin/gperf. </td> - <td> </td> - </tr> - - <tr><a name="o"> - <td><tt>-o</tt></td> - - <td>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 <tao_idl>is called. </td> - <td> </td> - </tr> - - <tr><a name="hc"> - <td><tt>-hc</tt></td> - - <td>Client's header file name ending. Default is "C.h".</td> - <td> </td> - </tr> - - <tr><a name="hs"> - <td><tt>-hs</tt></td> - - <td>Server's header file name ending. Default is "S.h".</td> - <td> </td> - </tr> - - <tr><a name="hT"> - <td><tt>-hT</tt></td> - - <td>Server's template header file name ending. Default is "S_T.h".</td> - <td> </td> - </tr> - - <tr><a name="cs"> - <td><tt>-cs</tt></td> - - <td>Client stub's file name ending. Default is "C.cpp".</td> - <td> </td> - </tr> - - <tr><a name="ci"> - <td><tt>-ci</tt></td> - - <td>Client inline file name ending. Default is "C.i".</td> - <td> </td> - </tr> - - <tr><a name="ss"> - <td><tt>-ss</tt></td> - - <td>Server skeleton file name ending. Default is "S.cpp".</td> - <td> </td> - </tr> - - <tr><a name="sT"> - <td><tt>-sT</tt></td> - - <td>Server template skeleton file name ending. Default is "S_T.cpp".</td> - <td> </td> - </tr> - - <tr><a name="si"> - <td><tt>-si</tt></td> - - <td>Server inline skeleton file name ending. Default is "S.i".</td> - <td> </td> - </tr> - - <tr><a name="st"> - <td><tt>-st</tt></td> - - <td>Server's template inline file name ending. Default is "S_T.i".</td> - <td> </td> - </tr> - - <tr><a name="t"> - <td><tt>-t</tt></td> - - <td>Temporary directory to be used by the IDL compiler. Default : - Resolve ACE_DEFAULT_TEMP_DIR_ENV. If it is not defined, choose - /tmp/. - </td> - <td> </td> - </tr> - - <tr><a name="Cw"> - <td><tt>-Cw</tt></td> - - <td>Output a warning if two identifiers in the same scope differ in - spelling only by case (default for now).</td> - <td> </td> - </tr> - - <tr><a name="Ce"> - <td><tt>-Ce</tt></td> - - <td>Output an error if two indentifiers in the same scope differ in - spelling only by case. Default output is warning (for now).</td> - - <td>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.</td> - </tr> - - <tr><a name="Gc"> - <td><tt>-Gc</tt></td> - - <td>Generate stubs and skeletons using compiled marshaling </td> - <td> </td> - </tr> - - <tr><a name="Gi"> - <td><tt>-Gi</tt></td> - - <td>Generate stubs and skeletons using interpretive marshaling (default - for now) </td> - <td> </td> - </tr> - - <tr><a name="Ge flag"> - <td><tt>-Ge </tt><i>flag</i></td> - - <td>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 </td> - <td> </td> - </tr> - - <tr><a name="Gp"> - <td><tt>-Gp </tt></td> - - <td>Generated collocated stubs that use <code>Thru_POA</code> collocation strategy (default)</td> - <td> </td> - </tr> - - <tr><a name="Gd"> - <td><tt>-Gd </tt></td> - - <td>Generated collocated stubs that use <code>Direct</code> collocation strategy</td> - <td> </td> - </tr> - - <tr><a name="Gt"> - <td><tt>-Gt</tt></td> - - <td>Generate optimized TypeCodes (unimplemented as yet)</td> - <td> </td> - </tr> - - <tr><a name="Gv"> - <td><tt>-Gv</tt></td> - - <td>Generate code that suppports Object-By-Value</td> - <td> </td> - </tr> - - <tr> - <td>-<tt>GI</tt></td> - - <td>Generate templates files for the servant implementation </td> - <td> </td> - </tr> - - <tr> - <td><tt>-GIh </tt><i>arg</i></td> - - <td>Servant implemenation header file name ending</td> - <td> </td> - </tr> - - <tr> - <td><tt>-GIs </tt><i>arg</i></td> - - <td>Servant implemenation skeleton file name ending</td> - <td> </td> - </tr> - - <tr> - <td><tt>-GIb </tt><i>arg</i></td> - - <td>Prefix to the implementation class names</td> - <td> </td> - </tr> - - <tr> - <td><tt>-GIe </tt><i>arg</i></td> - - <td>Suffix to the implementation class names</td> - <td> </td> - </tr> - - <tr> - <td><tt>-GIc </tt><i>arg</i></td> - - <td>Generate copy constructors in the servant implementation template files</td> - <td> </td> - </tr> - - <tr><a name="Sa"> - <td><tt>-Sa</tt></td> - - <td>Suppress generation of the Any operators</td> - <td> </td> - </tr> - - <tr><a name="Sp"> - <td><tt>-Sa</tt></td> - - <td>Suppress generation of collocated stubs that use <code>Thru_POA</code> collocation strategy</td> - <td> </td> - </tr> - - <tr><a name="Sd"> - <td><tt>-Sd</tt></td> - - <td>Suppress generation of collocated stubs that use <code>Direct</code> collocation strategy (default)</td> - <td> </td> - </tr> - - <tr><a name="St"> - <td><tt>-St</tt></td> - - <td>Suppress generation of the TypeCodes</td> - <td> </td> - </tr> -</table> <P> - -<P><HR><P> -Back to the TAO <A HREF="index.html">documentation</A>. - -<!--#include virtual="/~schmidt/cgi-sig.html" --> - -</body> -</html> |