$Id: README 94606 2011-10-06 09:41:14Z johnnyw $

                  IDL3 To IDL2 Converter

A pluggable back end used with the IDL compiler parser
and command line processor, this tool converts CCM-related
IDL constructs into their corresponding IDL2 equivalents,
in a new IDL file. For more information about CIAO, please see

$CIAO_ROOT/docs/releasenotes/index.html

COMPILING:

Use the provided .mpc file to generate a project or makefile to
compile the pluggable back end library and the executable.
Make sure the TAO IDL compiler front end is already built.

EXECUTABLE NAME:

tao_idl3_to_idl2

COMMAND LINE OPTIONS:

All the usual front-end command line options that apply to the IDL compiler
(such as path includes) work with this tool as well, since the IDL compiler
front end is simply reused. The options -? or -h will display a usage
message, including both front end and back end options. For a complete
list of IDL compiler command line options and a description of each, see
TAO/docs/compiler.html.

BACKEND OPTIONS:

-o <path> Also works the same as with the IDL compiler, setting the
output directory, overriding the default, which is the directory of
execution.

-e Generates a file foo_IDL2.idl from foo.idl that simply includes
foo.idl instead of generating its IDL declarations. Note that this
option takes effect only if foo.idl contains no 'IDL3' declarations,
otherwise it's a no-op.

Note that the original -x <filename> option (which manually excludes
an included IDL file from being transformed to an include of the
'_IDL2' decorated corresponding file) has been eliminated. This
option was intended for included IDL files that contained no IDL3
constructs, and therefore didn't need processing by this tool.
Detection of such included files is now automatic, and the processed
include filename will appear accordingly.

CAVEAT:

When using the TAO IDL compiler on files that are generated by this tool,
use the command line option -Sm on the IDL compiler, which will disable
the internal generation of equivalent IDL nodes in the AST. You'll notice
from the example below that the only ones that remain are eventtypes.
The -Sm option will prevent the IDL compiler from trying to create the
corresponding xxxConsumer interface, which now already exists explicitly
in IDL.

EXAMPLE CONVERSION:


// test.idl

#include <Components.idl>

interface Foo {};

eventtype Ev {};

component Bar
{
  uses multiple Foo needs_foo;
  publishes Ev ev_pub;
};

home BarHome manages Bar
{
};


Typing

tao_idl3_to_idl2 -I<CIAO_ROOT>/ciao -I<TAO_ROOT> test.idl

will generate



// test_IDL2.idl

#include "Components.idl"

interface Foo {};

eventtype Ev {};

interface EvConsumer : Components::EventConsumerBase
{
  void push_Ev (in Ev the_Ev);
};

interface Bar : Components::CCMObject
{
  struct needs_fooConnection
  {
    Foo objref;
    Components::Cookie ck;
  };

  typedef sequence<needs_fooConnection> needs_fooConnections;

  Components::Cookie connect_needs_foo (in Foo connection)
    raises (Components::ExceededConnectionLimit, Components::InvalidConnection);

  Foo disconnect_needs_foo (in Components::Cookie ck)
    raises (Components::InvalidConnection);

  needs_fooConnections get_connections_needs_foo ();

  Components::Cookie subscribe_ev_pub (in EvConsumer consumer)
    raises (Components::ExceededConnectionLimit);

  EvConsumer unsubscribe_ev_pub (in Components::Cookie ck)
    raises (Components::InvalidConnection);
};

interface BarHomeExplicit : Components::CCMHome
{
};

interface BarHomeImplicit : Components::KeylessCCMHome
{
  Bar create ()
    raises (Components::CreateFailure);
};

interface BarHome : BarHomeExplicit, BarHomeImplicit
{
};

