Documentation

Using the Metadata Generator

The metadata generator, as known as gen_bridge_metadata, is documented in a manual page. After having installed the project in your system, you can display the documentation:

$ man gen_bridge_metadata

About the BridgeSupport Format

Likewise the generator, the BridgeSupport XML format is documented in a manual page.

$ man BridgeSupport

There is also a DTD file available, that should be installed as /System/Library/DTDs/BridgeSupport.dtd.

Note that the documentation is still being written.

Quick Tutorial

Let's say you have some C code in which you have declared some type of structure which you would like to export to RubyCocoa or MacRuby (which also uses BridgeSupport for calling foreign code).

First, we create a header file containing the structure in question:

$ cat t.h
struct MapPoint {
int row;
int col;
};
typedef struct MapPoint MapPoint;

Next, we generate an exceptions template file based on this header file.

$ gen_bridge_metadata -F exceptions-template -c '-I.' t.h > exception.xml

The exceptions template file contains the name of our new struct. The generator uses an exception because we don't want to expose all C structures by default, giving the developer a choice. Here we leave it empty, which means MapPoint will be exposed.

$ cat exception.xml
<?xml version='1.0'?>
<!DOCTYPE signatures SYSTEM "file://localhost/System/Library/DTDs/BridgeSupport.dtd">
<signatures version='0.9'>
<struct name='MapPoint'/>
</signatures>

Now we generate the real .bridgesupport file, passing the exceptions file.

$ gen_bridge_metadata -e ./exception.xml -c '-I.' t.h > mappoint.bridgesupport

As you can see, it contains a signature for MapPoint.

$ cat mappoint.bridgesupport
<?xml version='1.0'?>
<!DOCTYPE signatures SYSTEM "file://localhost/System/Library/DTDs/BridgeSupport.dtd">
<signatures version='0.9'>
<struct name='MapPoint' type='{MapPoint=&quot;row&quot;i&quot;col&quot;i}'/>
</signatures>

And now it can be loaded from MacRuby/RubyCocoa and used as if it was a real Ruby class. Actually, it IS a real Ruby class :-)

$ macruby -e "load_bridge_support_file('mappoint.bridgesupport'); p MapPoint.new(1, 2)"
#<MapPoint row=1 col=2>