[cable] Needs an XML configuration file for CABLE

[Brad King]

Trygve,

> I'm not using cmake and need a sample XML configuration file for
> CABLE.  Does it exist documentation for the configuration file?

No one has ever tried to run CABLE without CMake for more than a
trivial example (as far as I know).  The documentation has never been
written.  Since CABLE/GCC-XML are in their very early stages, the
command-line interface hasn't been refined.  I'll try to write some
quick instructions, but it will probably be easier to use CMake to get
some examples, and then write support for it in your own build system.

Running GCC-XML/CABLE directly is a real pain since GCC-XML has to be
invoked with a bunch of options to make the source think it is another
compiler.  In particular, it must appear to be the compiler that will
be used to build the code generated by CABLE.  This is because CABLE
does some in-depth analysis of all the types used in the interface to
the class you are wrapping.  If these types refer at all to the
standard library, the generated code will reflect that.  The code must
be buildable by your compiler, so GCC-XML must use your compiler's
standard includes.

One other thing to keep in mind is that you must use the version of
GCC-XML that is in a release tarball (or the binary).  The current
version in CVS will NOT work with CABLE.  GCC-XML is being re-written,
and CABLE hasn't yet been updated.

Given the above, here are some quick instructions to try:

Say we are creating wrappers for a "Foo" library with two headers:

fooClass1.h implements classes "foo" and "myfoo"
fooClass2.h implements classes "bar" and "mybar"

First, create input files for GCC-XML:

---- gccxml_fooClass1.cxx ----
#include "fooClass1.h"
------------------------------

---- gccxml_fooClass2.cxx ----
#include "fooClass2.h"
------------------------------

Run GCC-XML on these files:

gccxml [lots-of-fancy-options] -fxml=fooClass1.xml gccxml_fooClass1.cxx
gccxml [lots-of-fancy-options] -fxml=fooClass2.xml gccxml_fooClass2.cxx

For the "fancy options", see the GCC-XML documentation.

Write one config file corresponding to each run of GCC-XML (a "group"):

----- cable_fooClass1.xml -----
<CableConfiguration source="fooClass1.xml" group="foo1">
  <Header name="fooClass1.h"/>
  <Class name="foo"/>
  <Class name="myfoo"/>
</CableConfiguration>
-------------------------------

----- cable_fooClass2.xml -----
<CableConfiguration source="fooClass2.xml" group="foo2">
  <Header name="fooClass2.h"/>
  <Class name="bar"/>
  <Class name="mybar"/>
</CableConfiguration>
-------------------------------

Note that the "Header" entries above correspond to the files included by
the GCC-XML input files.  The "Class" entry can be repeated for as many
classes as are defined in the header file's translation unit. The GCC-XML
input files need to be slightly more advanced if you want to wrap template
classes.  The "group" name can be any valid C identifier, as long as it
matches with the group names listed in the package config file below.

Write one config file corresponding to the generated Tcl package.  It
lists all the groups for the package.  The package name should match
the name of the library that will be generated.

-------- cable_Foo.xml --------
<CableConfiguration package="Foo">
  <Group name="foo1"/>
  <Group name="foo2"/>
</CableConfiguration>
-------------------------------

Run cable on all config files:

cable cable_fooClass1.xml -tcl fooClass1_tcl.cxx
cable cable_fooClass2.xml -tcl fooClass2_tcl.cxx
cable cable_Foo.xml -tcl fooPackage_tcl.cxx

Compile these files with your compiler, giving it the include path to
the Cable installation.  Link them into a library called "libFoo.a",
"libFoo.sh", "Foo.dll", or whatever your platform names it.  You
should then be able to load the library as documented on the CABLE
homepage.

I'd like to clean up this command-line interface after the GCC-XML
re-write, so I'd be interested in your feedback.

Good luck,
-Brad