<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.05">
<TITLE>
The IDL compiler
</TITLE>
</HEAD>
<BODY >
<A HREF="omniORBpy004.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="omniORBpy006.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>
<H1>Chapter 5 The IDL compiler</H1>
<A NAME="chap:omniidl"></A>omniORBpy uses a new IDL compiler, named omniidl, which is also used
by omniORB 3. It consists of a generic front-end parser written in
C++, and a number of back-ends written in Python. omniidl is very
strict about IDL validity, so you may find that it reports errors in
IDL which compiles fine with earlier versions of omniORB, and with
other ORBs.<BR>
<BR>
The general form of an omniidl command line is:<BR>
<BR>
<BLOCKQUOTE> <TT>omniidl </TT>[<I>options</I>]<TT> -b</TT><<I>back-end</I>><TT> </TT>[<I>back-end options</I>]<TT> </TT><<I>file 1</I>><TT> </TT><<I>file 2</I>><TT> </TT>...</BLOCKQUOTE><A NAME="toc19"></A>
<H2>5.1 Common options</H2>The following options are common to all back-ends:<BR>
<BR>
<TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD ALIGN=left NOWRAP></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-D</TT><I>name</I>[<TT>=</TT><I>value</I>]</TD>
<TD ALIGN=left NOWRAP>Define <I>name</I> for the preprocessor.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-U</TT><I>name</I></TD>
<TD ALIGN=left NOWRAP>Undefine <I>name</I> for the preprocessor.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-I</TT><I>dir</I></TD>
<TD ALIGN=left NOWRAP>Include <I>dir</I> in the preprocessor search path.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-E</TT></TD>
<TD ALIGN=left NOWRAP>Only run the preprocessor, sending its output to stdout.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-Y</TT><I>cmd</I></TD>
<TD ALIGN=left NOWRAP>Use <I>cmd</I> as the preprocessor, rather than the normal C
preprocessor.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-N</TT></TD>
<TD ALIGN=left NOWRAP>Do not run the preprocessor.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-T</TT></TD>
<TD ALIGN=left NOWRAP>Use a temporary file, not a pipe, for preprocessor output.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-Wp</TT><I>arg</I>[,<I>arg</I>...]</TD>
<TD ALIGN=left NOWRAP>Send arguments to the preprocessor.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-b</TT><I>back-end</I></TD>
<TD ALIGN=left NOWRAP>Run the specified back-end. For omniORBpy, use <TT>-bpython</TT>.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-Wb</TT><I>arg</I>[,<I>arg</I>...]</TD>
<TD ALIGN=left NOWRAP>Send arguments to the back-end.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-nf</TT></TD>
<TD ALIGN=left NOWRAP>Do not warn about unresolved forward declarations.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-k</TT></TD>
<TD ALIGN=left NOWRAP>Keep comments after declarations, to be used by some back-ends.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-K</TT></TD>
<TD ALIGN=left NOWRAP>Keep comments before declarations, to be used by some back-ends.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-C</TT><I>dir</I></TD>
<TD ALIGN=left NOWRAP>Change directory to <I>dir</I> before writing output files.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-d</TT></TD>
<TD ALIGN=left NOWRAP>Dump the parsed IDL then exit, without running a back-end.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-p</TT><I>dir</I></TD>
<TD ALIGN=left NOWRAP>Use <I>dir</I> as a path to find omniidl back-ends.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-V</TT></TD>
<TD ALIGN=left NOWRAP>Print version information then exit.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-u</TT></TD>
<TD ALIGN=left NOWRAP>Print usage information.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-v</TT></TD>
<TD ALIGN=left NOWRAP>Verbose: trace compilation stages.</TD>
</TR></TABLE><BR>
Most of these options are self explanatory, but some are not
so obvious.<BR>
<BR>
<H3>5.1.1 Preprocessor interactions</H3>IDL is processed by the C preprocessor before omniidl parses it.
Unlike the old IDL compiler, which used different C preprocessors on
different platforms, omniidl always uses the GNU C preprocessor (which
it builds with the name omnicpp). The <TT>-D</TT>, <TT>-U</TT>, and
<TT>-I</TT> options are just sent to the preprocessor. Note that the
current directory is not on the include search path by default---use
`<TT>-I.</TT>' for that. The <TT>-Y</TT> option can be used to
specify a different preprocessor to omnicpp. Beware that line
directives inserted by other preprocessors are likely to confuse
omniidl.<BR>
<BR>
<H4> Windows 9x</H4>The output from the C preprocessor is normally fed to the omniidl
parser through a pipe. On some Windows 98 machines (but not all!) the
pipe does not work, and the preprocessor output is echoed to the
screen. When this happens, the omniidl parser sees an empty file, and
produces useless stub files with strange long names. To avoid the
problem, use the `<TT>-T</TT>' option to create a temporary file
between the two stages.<BR>
<BR>
<H3>5.1.2 Forward-declared interfaces</H3>If you have an IDL file like:<BR>
<BR>
<PRE>
interface I;
interface J {
attribute I the_I;
};
</PRE>then omniidl will normally issue a warning:<BR>
<BR>
<PRE>
test.idl:1: Warning: Forward declared interface `::I' was never
fully defined
</PRE>It is illegal to declare such IDL in isolation, but it
<EM>is</EM> valid to define interface <TT>I</TT> in a separate file. If
you have a lot of IDL with this sort of construct, you will drown
under the warning messages. Use the <TT>-nf</TT> option to suppress
them.<BR>
<BR>
<H3>5.1.3 Comments</H3>By default, omniidl discards comments in the input IDL. However, with
the <TT>-k</TT> and <TT>-K</TT> options, it preserves the comments
for use by the back-ends. The C++ back-end ignores this information,
but it is relatively easy to write new back-ends which <EM>do</EM> make
use of comments.<BR>
<BR>
The two different options relate to how comments are attached to
declarations within the IDL. Given IDL like:<BR>
<BR>
<PRE>
interface I {
void op1();
// A comment
void op2();
};
</PRE>the <TT>-k</TT> flag will attach the comment to <TT>op1()</TT>;
the <TT>-K</TT> flag will attach it to <TT>op2()</TT>.<BR>
<BR>
<A NAME="toc20"></A>
<H2>5.2 Python back-end options</H2>
<A NAME="sec:Wbglobal"></A>When you specify the Python back-end (with <TT>-bpython</TT>), the
following <TT>-Wb</TT> options are available. Note that the
<TT>-Wb</TT> options must be specified <EM>after</EM> the
<TT>-bpython</TT> option, so omniidl knows which back-end to give the
arguments to.<BR>
<BR>
<TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD ALIGN=left NOWRAP></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-Wbstdout</TT></TD>
<TD ALIGN=left NOWRAP>Send the generated stubs to standard output, rather than to a
file.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-Wbinline</TT></TD>
<TD ALIGN=left NOWRAP>Output stubs for #included files in line with the main
file.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-Wbglobal=</TT><I>g</I></TD>
<TD ALIGN=left NOWRAP>Use <I>g</I> as the name for the global IDL scope (default
<TT>_GlobalIDL</TT>).</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-Wbpackage=</TT><I>p</I></TD>
<TD ALIGN=left NOWRAP>Put both Python modules and stub files in package
<I>p</I>.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-Wbmodules=</TT><I>p</I></TD>
<TD ALIGN=left NOWRAP>Put Python modules in package <I>p</I>.</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>-Wbstubs=</TT><I>p</I></TD>
<TD ALIGN=left NOWRAP>Put stub files in package <I>p</I>.</TD>
</TR></TABLE><BR>
The <TT>-Wbstdout</TT> option is not really useful if you are
invoking omniidl yourself. It is used by <TT>omniORB.importIDL()</TT>,
described in section <A HREF="omniORBpy006.html#sec:importIDL">6.12</A>.<BR>
<BR>
When you compile an IDL file which #includes other IDL files, omniidl
normally only generates code for the main file, assuming that code for
the included files will be generated separately. Instead, you can use
the <TT>-Wbinline</TT> option to generate code for the main IDL file
<EM>and</EM> all included files in a single stub file.<BR>
<BR>
Definitions declared at IDL global scope are normally placed in a
Python module named `<TT>_GlobalIDL</TT>'. The <TT>-Wbglobal</TT>
allows you to change that.<BR>
<BR>
As explained in section <A HREF="omniORBpy002.html#sec:generatingStubs">2.2</A>, when you compile an
IDL file like:<BR>
<BR>
<PRE>
// echo_example.idl
module Example {
interface Echo {
string echoString(in string mesg);
};
};
</PRE>omniidl generates directories named <TT>Example</TT> and
<TT>Example__POA</TT>, which provide the standard Python mapping
modules, and also the file <TT>example_echo_idl.py</TT> which contains
the actual definitions. The latter file contains code which inserts
the definitions in the standard modules. This arrangement means that
it is not possible to move all of the generated code into a Python
package by simply placing the files in a suitably named directory.
You may wish to do this to avoid clashes with names in use elsewhere
in your software.<BR>
<BR>
You can place all generated code in a package using the
<TT>-Wbpackage</TT> command line option. For example,<BR>
<BR>
<BLOCKQUOTE>
<TT>omniidl -bpython -Wbpackage=generated echo_example.idl</TT>
</BLOCKQUOTE>creates a directory named `<TT>generated</TT>', containing the
generated code. The stub module is now called
`<TT>generated.Example</TT>', and the actual stub definitions are in
`<TT>generated.example_echo_idl</TT>'. If you wish to split the
modules and the stub definitions into different Python packages, you
can use the <TT>-Wbmodules</TT> and <TT>-Wbstubs</TT> options.<BR>
<BR>
Note that if you use these options to change the module package, the
interface to the generated code is not strictly-speaking CORBA
compliant. You may have to change your code if you ever use a Python
ORB other than omniORBpy.<BR>
<BR>
<A NAME="toc21"></A>
<H2>5.3 Examples</H2>Generate the Python stubs for a file <TT>a.idl</TT>:<BR>
<BR>
<BLOCKQUOTE>
<TT>omniidl -bpython a.idl</TT>
</BLOCKQUOTE>As above, but put the stubs in a package called
`<TT>stubs</TT>':<BR>
<BR>
<BLOCKQUOTE>
<TT>omniidl -bpython -Wbstubs=stubs a.idl</TT>
</BLOCKQUOTE>Generate both Python and C++ stubs for two IDL files
(requires omniORB 3):<BR>
<BR>
<BLOCKQUOTE>
<TT>omniidl -bpython -bcxx a.idl b.idl</TT>
</BLOCKQUOTE>Just check the IDL files for validity, generating no output:<BR>
<BR>
<BLOCKQUOTE>
<TT>omniidl a.idl b.idl</TT>
</BLOCKQUOTE><HR>
<A HREF="omniORBpy004.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="omniORBpy006.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
distrib
>
Mandriva
>
8.2
>
i586
>
media
>
contrib
>
by-pkgid
>
51adff6dc4cce5d695a2dcdb26f1a3d7
>
files
>
321
