Thrown together by Andreas Kloeckner <ak@ixion.net>.
With contributions from Bruce Ide <nride@uswest.net>.

-------------------------------------------------------------------------------
Q. What versions of everything?
-------------------------------------------------------------------------------

gcc: 2.95.2, at least. Anything below that version busts you with some 
message over not understanding some template in conjunction with an
overloaded "operator new".

-------------------------------------------------------------------------------
Q. Why is it important that I install ORBit-C++ to the _exact_ same place
   as ORBit(-C)?
-------------------------------------------------------------------------------

A: Because the IDL compiler is a shared library backend for orbit-idl,
and it won't be found unless it is in its standard location. Of course,
you may install to some different place, but then you should either

a) symlink <orbit-prefix>/lib/orbit-idl to your custom prefix
or
b) use the --backenddir option of orbit-idl.

-------------------------------------------------------------------------------
Q. How do I compile my first ORBit-C++ app?
-------------------------------------------------------------------------------

Write an IDL file, say "hiworld.idl". [IDL: http://www.omg.org]
Run those four commands in order:

To generate and compile the C portion:

> orbit-idl -lc hiworld.idl
> gcc -c hiworld*.c `orbit-config --cflags server client`

To generate and compile the C++ portion:

> orbit-idl -lc++ hiworld.idl
> c++ -c hiworld.cc `orbitcpp-config --cflags server client`

Then you may proceed to write your client and server interface code and compile
and link your application.

That's how to compile. How to actually create working objects is
slightly more difficult (But only slightly.) Essentially the IDL
creates a base class from which you derive an implementation which
actually does the work. I've not done much of this myself yet, so
now's the time to go look at those examples again.

If this is all too fast, there's example code up at 
ftp://orbitcpp.sourceforge.net/pub/orbitcpp.

-------------------------------------------------------------------------------
Q. I tried to use some STL in a private variable and the compile
   didn't work...
-------------------------------------------------------------------------------

I think it's a GCC thing, not an ORBit-C++ thing. It may be I didn't
install GCC correctly, it may be there's a bug, it may be I'm doing
something stupid. I need to investigate this some more. (Bruce Ide,
nride@uswest.net)

-------------------------------------------------------------------------------
Q. Why is ORBit-C++ only a wrapper around ORBit-C, anyway?
-------------------------------------------------------------------------------

Three reasons:

a) speed
b) compatibility
c) developer laziness

It is much more hassle to create a mapping from scratch than base it upon
a ready-made mapping, especially in the case of C and C++. The C code comes
out well-optimized and nicely debugged. Why should we write a new compiler
from scratch if all wrapping operations (except exception packing, granted)
have O(1) complexity?

(by O(1) I mean "no data copying")

-------------------------------------------------------------------------------
Q. What about threads?
-------------------------------------------------------------------------------

ORBit is not currently thread-safe, but there is a version that
supports threads called ORBit-mt. Checkout
http://orbit-resource@sourceforge.net for a link to this.

ORBit-C++ shouldn't have any thread unsafe constructs, and thus should
work with ORBit-mt. This hasn't been tested thoroughly though.

ORBit2 should in theory be thread-safe. When ORBit-C++ starts tracking ORBit2,
it should also, in theory, be thread-safe.


-------------------------------------------------------------------------------
Q. I get spurious segfaults in exception handling when linking with 
   liborbitcpp.
-------------------------------------------------------------------------------

This one is also hairy, and I do not have a full understanding of why or
what or where it comes from. However, I know a workaround.

[snip] -------------------------------------------------
--- ltmain.sh.old	Tue Apr 11 02:36:10 2000
+++ ltmain.sh	Tue Apr 11 02:36:22 2000
@@ -1797,7 +1797,7 @@
 	  ;;
 	*)
 	  # Add libc to deplibs on all other systems.
-	  deplibs="$deplibs -lc"
+	  # deplibs="$deplibs -lc"
 	  ;;
 	esac
       fi
[snip] -------------------------------------------------

Locate your copy of ltmain.sh, and apply this patch to it, then run

make maintainer-clean && autogen.sh

WARNING. Watch out. If you apply this patch, you may harm your libtool 
installation. If you do so, you are definitely on your own. Your libtool 
may not work as before, since, as I said, I've just found out 
how to eliminate the segfaults, I don't know exactly what I'm doing.

BTW: compiling a new glibc (2.1.3) also fixed the problem for me. 
