[orbitcpp-list] Updated Orbit-C++ FAQ

[Mark G. <mar...@ya...>]

All,

Here is the updated FAQ. There are still unanswered
questions left. So, if you've got any input, send it
on and I'll be sure to incorporate it.

Note, I've marked my own comments and questions within
brackets.

Thanks,
Mark

----

ORBit-C++ FAQ

0. Administrivia

0.1. Version

This is version 0.2 of the FAQ, released on [???].

0.2. Authors

This FAQ was originally written by Andrew Smith. It is
being updated by Mark Gunn. It is the distilled wisdom
of Phil Dawes, Ronald Garcia, Andreas Kloeckner [any
other names I should put here?] and other posters 
to the orb...@li... mailing
list.

1. General

1.1. What is ORBit-C++?

ORBit-C++ is a project whose goal is to provide a C++
mapping for the ORBit project's CORBA 2.2 compliant
ORB. If that doesn't make sense, then you should read
up on CORBA and ORBit. See the "Related Information"
section below.)

1.2. How does it relate to ORBit?

Currently, ORBit only provides a C CORBA mapping.
ORBit-C++ provides the C++ "bindings" to the C
mapping. In other words, ORBit-C++ generates code that
marshals CORBA C++ class functions to the ORBit
generated CORBA C functions. For C++ programmers, it
appears that they are using C++ mappings directly.
Access to CORBA objects through ORBit is done without
having to wrap them manually. Conversely, CORBA
objects can be
implemented in C++ and used by C programmers without
having to deal with C++ name mangling issues.

1.3. Is there a mailing list?

Yes, it is called orb...@li...
and is currently hosted by SourceForge. To join, check
out the web site:

http://lists.sourceforge.net/mailman/listinfo/orbitcpp-list

1.4. Is there a web site?

Yes, it is:

   http://orbitcpp.sourceforge.net/

2. Compiling & Installing

2.1. How do I get the source?

The source code is available from the SourceForge
anonymous CVS server. To check it out, use the
following commands:

   $ export
CVSROOT='-d:pserver:ano...@cv...:/cvsroot/orbitcpp'
   $ cvs login
   [There is no password, just hit return.]
   $ cvs -z3 checkout ORBit-C++

Once you have a version checked out, you can update it
by using the
following command:

   $ cvs -z3 update -dP ORBit-C++

The -z3 switch enables compression; note that the
GNOME CVS maintainers request that you don't specify a
compression level higher than 3 to keep the load on
the machine down. The -dP switches ensure that any
additional new directories are downloaded and that
obsolete ones are pruned. For more information read
the SourceForge CVS documentation: 
	http://sfdocs.sourceforge.net/sfdocs/site/cvs.php

2.2. What software do I need to compile it?

You will need the following software installed to
compile the source:

        egcs [?]
        automake [?]
        autoconf [?]
        ORBit [?]
        glib [?]
        [any others?]

The version numbers listed are the minimum known to
work. Make sure you have the development portions of
ORBit and glib as well, otherwise you will be missing
some of the required header files.

2.3. How do I compile it?

First, you need to generate all the make files. In the
top directory, run the "autogen.sh" script. Second,
still in the top directory, run the command "make". 
This is also described in the INSTALL file.

[What is the difference between running the configure
command and executing the autogen.sh script file?
Also, I've noticed that the *.tar.gz file does not
usually contain an autogen.sh script file. 

2.4. It's compiled, now what?

You need to install it. To do this, in the top
directory run the command "make install". [Correct me
if I'm wrong, but you need root priveledges to
install.] This will allow you to use the orbit-idl
command to generate the C and C++ bindings on IDL
files.

2.6 What is the name of the Orbit-C++ idl compiler?

It is orbit-idl.

2.7 Is this the same as the Orbit idl compiler?

Yes. However, the Orbit-C++ idl compiler acts as a
backend compiler to the Orbit idl compiler.

3. Using

3.1. How do I compile my IDL file?

Once you have compiled and installed the code, issue
the following
commands: 

	orbit-idl -l c test.idl
        orbit-idl -l c++ test.idl

This will generate the c++ code, which will wrap the
generated c code.

3.2. Why won't my IDL file compile?

Work on the idl-compiler is still in progress. [I'm
not sure what is and isn't done; so, I removed what
was here. Perhaps we could be vague here and reference
the hacking file for features not implemented here. Or
suggest they query the list. Suggestions?] 

3.3. Why do the .cc files have "-cpp-" in the name?

ORBit-C++ generated files must be compiled with ORBit
generated files. The "-cpp-" is added to prevent the
object files from clashing. For instance:

        foo-stubs.c  -> foo-stubs.o
        foo-stubs.cc -> foo-stubs.o

This is rectified by:

        foo-stubs.c      -> foo-stubs.o
        foo-cpp-stubs.cc -> foo-cpp-stubs.o

4. Development

4.1. How can I help?

First, subscribe to the mailing list and read up on
what work is currently being done. Secondly, check out
the code and see if you can compile it. If this works,
try some of the test cases. Whatever happens, let the
mailing list know how you got on.

If you want to contribute code, look at the HACKING
file to see what needs doing. Also, check with the
mailing list as well. Writing test cases would also be
useful. Of course, there is always more need for
documentation.

4.5. How do I submit code?

If you have write access to the SOURCEFORGE CVS
archive, then just use the following command:

        $ cvs commit

If you have not got write access, then the best thing
to do is create a unified diff patch against the CVS
archive. You can do this with the following command:

        $ cvs -z3 diff -RNu ORBit-C++ > patchfile

This will pick up all of the changes you have made,
including files that have been created or deleted. It
is helpful if you put the date in the patch file name,
something like "orbitcpp-19990814.patch" is good. Mail
the patch file to the list and one of the core
developers will apply it to the CVS archive. If you
find yourself submitting a lot of patches,
then it is time to get a write access account for the
SOURCEFORGE CVS archive. Mail the list for details,
although you will probably be spotted by one of the
core developers first if it comes to this.

[There's a lot of good information information in
HACKING file. Should we merge some of that information
into here? Or keep it separate and just reference it
from here?]

5. Testing

5.1 How do I test it?

Each directory under the test directory contains code
for a simple test case. The README file explains what
functionality is being tested and what to do.
Generally, all you need to do is run make in the
directory. If it builds, try the following commands:

        ./server > iorfile &
        ./client `cat iorfile`

The output should give some indication of success or
otherwise.

6. Related Information

The CORBA 2.2 specification is available at:

        http://www.omg.org/corba/corbaiiop.html

[I'm not sure if this url is still valid. I tried
checking it, but I couldn't get to the OMG site. So,
I'll check it later.]

It is provided in PostScript and PDF formats, but
there is no  (official) online version.

The ORBit homepage is at:

        http://www.labs.redhat.com/orbit/

__________________________________________________
Do You Yahoo!?
Send online invitations with Yahoo! Invites.
http://invites.yahoo.com