PyORBit
=======

This is a Python language binding for the ORBit2 CORBA implementation.
It aims to take advantage of new features found in ORBit2 to make
language bindings more efficient.  This includes:
  - Use of ORBit2 type libraries to generate stubs
  - use of the ORBit_small_invoke_stub() call for operation
    invocation, which allows for short circuited invocation on local
    objects.

Where it makes sense, this binding tries to stay compatible with the
Python language mapping, which can be found on the OMG web site:
    http://www.omg.org/cgi-bin/doc?formal/02-09-07

Currently only the client side of the binding has been done.


Required ORBit2 Version
-----------------------

Unfortunately, ORBit2 2.4.3 contains a number of bugs that can cause
problems for PyORBit.  This can include crashing the python
interpreter, and crashing remote objects.

You will need to upgrade to either ORBit2 2.5.x (taken from the HEAD
branch), use a CVS checkout from the gnome-2-0 branch or wait for
ORBit2 2.4.4.

As some of the bugs were in the IDL compiler, you may need to
recompile code generated by the IDL compiler.  This includes the
"Bonobo" typelib (distributed with libbonobo), and probably other
libraries.


Typelibs
--------

Before using an interface, you should build a typelib for it.  The
basic steps are:

 $ orbit-idl-2 --imodule filename.idl
 $ gcc -fPIC -c filename-imodule.c `pkg-config --cflags ORBit-2.0`
 $ gcc -shared -o filename_module.so filename-imodule.o \
        `pkg-config --libs ORBit-2.0`

You can then install the imodule in $(prefix)/lib/orbit-2.0.

Alternatively, you can install it somewhere else and set the
ORBIT_TYPELIB_PATH environment variable to point at it.

You can then load the typelib with the following python statement:

 >>> ORBit.load_typelib('filename')

This will generate stubs for all the types in the IDL file.


Automatic Type Discovery
------------------------

If you are only interested in acting as a client (ie. calling
operations on objects), then it may not be necessary to build a
typelib.  ORBit2 includes introspection support that allows PyORBit to
snarf typelib information from an object reference, provided that the
server is implemented with ORBit2.

This makes client side operation almost painless.
