# Chapter 5 The IDL compiler

omniORB 3 has a brand new IDL compiler, named omniidl. 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.
The general form of an omniidl command line is:

> `omniidl` [options]`-b`<back-end>`` [back-end options]`` <file 1>`` <file 2>`` ...

## 5.1 Common options

The following options are common to all back-ends:

`-D` name[`=`value] | Define name for the preprocessor.
`-U` name | Undefine name for the preprocessor.
`-I` dir | Include dir in the preprocessor search path.
`-E` | Only run the preprocessor, sending its output to stdout.
`-Y` cmd | Use cmd as the preprocessor, rather than the normal C preprocessor.
`-N` | Do not run the preprocessor.
`-T` | Use a temporary file, not a pipe, for preprocessor output.
`-Wp` arg[,arg...] | Send arguments to the preprocessor.
`-b` back-end | Run the specified back-end. For the C++ ORB, use `-bcxx`.
`-Wb` arg[,arg...] | Send arguments to the back-end.
`-nf` | Do not warn about unresolved forward declarations.
`-k` | Keep comments after declarations, to be used by some back-ends.
`-K` | Keep comments before declarations, to be used by some back-ends.
`-C` dir | Change directory to dir before writing output files.
`-d` | Dump the parsed IDL then exit, without running a back-end.
`-p` dir | Use dir as a path to find omniidl back-ends.
`-V` | Print version information then exit.
`-u` | Print usage information.
`-v` | Verbose: trace compilation stages.

Most of these options are self explanatory, but some are not so obvious.

### 5.1.1 Preprocessor interactions

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 `-D`, `-U`, and `-I` options are just sent to the preprocessor. Note that the current directory is not on the include search path by default---use ``-I.`' for that. The `-Y` option can be used to specify a different preprocessor to omnicpp. Beware that line directives inserted by other preprocessors are likely to confuse omniidl.

#### Windows 9x

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 ``-T`' option to create a temporary file between the two stages.

### 5.1.2 Forward-declared interfaces

If you have an IDL file like:

    interface I;
    interface J {
      attribute I the_I;
    };

then omniidl will normally issue a warning:

      test.idl:1: Warning: Forward declared interface `::I' was never
      fully defined

It is illegal to declare such IDL in isolation, but it is valid to define interface `I` 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 `-nf` option to suppress them.

### 5.1.3 Comments

By default, omniidl discards comments in the input IDL. However, with the `-k` and `-K` 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 do make use of comments.
The two different options relate to how comments are attached to declarations within the IDL. Given IDL like:

    interface I {
      void op1();
      // A comment
      void op2();
    };

the `-k` flag will attach the comment to `op1()`; the `-K` flag will attach it to `op2()`.

## 5.2 C++ back-end options

When you specify the C++ back-end (with `-bcxx`), the following `-Wb` options are available. Note that the `-Wb` options must be specified after the `-bcxx` option, so omniidl knows which back-end to give the arguments to.

`-Wbh=`suffix | Use suffix for generated header files. Default ``.hh`'.
`-Wbs=`suffix | Use suffix for generated stub files. Default ``SK.cc`.'
`-Wbd=`suffix | Use suffix for generated dynamic files. Default ``DynSK.cc`.'
`-Wba` | Generate stubs for TypeCode and Any.
`-Wbtp` | Generate `tie' implementation skeletons.
`-Wbtf` | Generate flattened `tie' implementation skeletons.
`-Wbsplice-modules` | Splice together multiply-opened modules into one.
`-Wbexample` | Generate example implementation code.
`-WbF` | Generate code fragments (for experts only).
`-WbBOA` | Generate BOA compatible skeletons.
`-Wbold` | Generate old CORBA 2.1 signatures for skeletons.
`-Wbold_prefix` | Map C++ reserved words with prefix ``_`' rather than ``_cxx_`'.
`-Wbkeep_inc_path` | Preserve IDL ``#include`' paths in generated ``#include`' directives.
`-Wbuse_quotes` | Use quotes in ``#include`' directives (e.g. `"foo"` rather than `<foo>`.)

Again, most of these are self-explanatory.

### 5.2.1 Module splicing

On C++ compilers without namespace support, IDL modules map to C++ classes, and so cannot be reopened. For some IDL, it is possible to `splice' reopened modules on to the first occurrence of the module, so all module definitions are in a single class. It is possible in this sort of situation:

    module M1 {
      interface I {};
    };
    module M2 {
      interface J {
        attribute M1::I ok;
      };
    };
    module M1 {
      interface K {
        attribute I still_ok;
      };
    };

but not if there are cross-module dependencies:

    module M1 {
      interface I {};
    };
    module M2 {
      interface J {
        attribute M1::I ok;
      };
    };
    module M1 {
      interface K {
        attribute M2::J oh_dear;
      };
    };

In both of these cases, the `-Wbsplice-modules` option causes omniidl to put all of the definitions for module `M1` into a single C++ class. For the first case, this will work fine. For the second case, class `M1::K` will contain a reference to `M2::J`, which has not yet been defined; the C++ compiler will complain.

### 5.2.2 Flattened tie classes

Another problem with mapping IDL modules to C++ classes arises with tie templates. The C++ mapping says that for the interface `M::I`, the C++ tie template class should be named `POA_M::I_tie`. However, since template classes cannot be declared inside other classes, this naming scheme cannot be used with compilers without namespace support.
The standard solution is to produce `flattened' tie class names, using the `-Wbtf` command line argument. With that flag, the template class is declared at global scope with the name `POA_M_I_tie`. i.e. all occurrences of ``::`' are replaced by ``_`'.

### 5.2.3 Generating example implementations

If you use the `-Wbexample` flag, omniidl will generate an example implementation file as well as the stubs and skeletons. For IDL file `foo.idl`, the example code is written to `foo_i.cc`. The example file contains class and method declarations for the operations of all interfaces in the IDL file, along with a `main()` function which creates an instance of each object. You still have to fill in the operation implementations, of course.

## 5.3 Examples

Generate the C++ headers and stubs for a file `a.idl`:

> `omniidl -bcxx a.idl`

Generate with Any support:

> `omniidl -bcxx -Wba a.idl`

Compile two files with Any support:

> `omniidl -bcxx -Wba a.idl b.idl`

As above, but also generate Python stubs for the files (assuming omniORBpy is installed):

> `omniidl -bcxx -Wba -bpython a.idl b.idl`

Just check the IDL files for validity, generating no output:

> `omniidl a.idl b.idl`