Manual Pages for UNIX Darwin command on man gen_bridge

Manual Pages for UNIX Darwin command on man gen_bridge_metadata

GENBRIDGEMETADATA(1) BSD General Commands Manual GENBRIDGEMETADATA(1)

NAME

ggeennbbrriiddggeemmeettaaddaattaa - Objective-C Bridges Metadata Generator

SYNOPSIS

ggeennbbrriiddggeemmeettaaddaattaa [options...] headers...

DESCRIPTION

ggeennbbrriiddggeemmeettaaddaattaa is a tool that generates bridging metadata informa-

tion for a given framework or set of headers. The Objective-C bridges

supported in Mac OS X, such as RubyCocoa (Ruby) and PyObjC (Python), read this information at runtime.

Metadata files describe the parts of an Objective-C framework that the

bridges cannot automatically handle. These are primarily the ANSI C ele-

ments of the framework - functions, constants, enumerations, and so on

- but also include special cases such as functions or methods that

accept pointer-like arguments. These special cases must be manually spec-

ified in separate files called exceptions. The ggeennbbrriiddggeemmeettaaddaattaa tool can then read in the exceptions file when it generates the framework metadata. The file extension used for metadata files should be ..bbrriiddggeessuuppppoorrtt. Certain elements, such as inline functions, cannot be described in the metadata files. It is therefore required to generate a dynamic library in order to make the bridges use them. The genbridgemetadata tool can take care of that for you. The file extension for the dynamic libraries should be ..ddyylliibb. You should install metadata files in one of three filesystem locations. For example, for a framework named MyFramework that is installed as /Library/Frameworks/MyFramework.framework, you can install the

MyFramework.bridgesupport and MyFramework.dylib files in one of the fol-

lowing possible locations, in order of priority: ++oo /Library/Frameworks/MyFramework/Resources/BridgeSupport ++oo /Library/BridgeSupport ++oo ~/Library/BridgeSupport OOPPTTIIOONNSS

The ggeennbbrriiddggeemmeettaaddaattaa tool accepts the following command-line options:

-ff framework, --ffrraammeewwoorrkk framework

Generates metadata for the given framework. This argument can

accept both the name of a framework of an absolute path to a frame-

work. When passing a framework name, the program will try to locate the framework in one of the standard framework locations.

-pp, --pprriivvaattee

Generates metadata based on the private headers of the given frame-

works. This argument must be used with the -ff argument.

-FF format, --ffoorrmmaatt format

Selects the metadata format that will be generated. Possible values are: final The final metadata format. This is the default value. dylib The dynamic library format. This is only

required if you want to support inline func-

tions. In order to use this format you need to

pass a value for the -oo argument.

exceptions-template This will generate an exception template.

Please consult BridgeSupport(5) for more details about the exception format. Once your exception file is finished you can pass it to

the -ee argument in order to generate the final

metadata.

-ee file, --eexxcceeppttiioonn file

Considers the given exception file when generating the final meta-

data format. The given exception file must conform to a certain for-

mat, described in bridgeSupport(5). Exception files are manually

written, but you can generate a template by passing -FF

exceptions-template to the generator.

--6644-bbiitt

Writes 64-bit annotations to the final metadata format. In order to

use this option you need to run the generator on a 64-bit machine.

The generation will take a bit more than twice the time, as it will

have to collect both 32-bit and 64-bit annotations, and then merge

them into a single document.

-cc, --ccffllaaggss flags

Provides custom flags that will be passed to the C compiler. The

generator compiles and executes several C and Objective-C programs

during the generation of the final metadata format. Some flags are determined by default, but you might want to provide your own flags according to the piece of code you want to generate metadata for (for example, a framework part of a umbrella framework).

-CC, --ccffllaaggss-6644 flags

Provides custom flags that will be passed to the C compiler, when

generating 64-bit annotations. By default the same flags are passed

to the C compiler when generating both 32-bit and 64-bit annota-

tions.

-oo, --oouuttppuutt file

Writes the output to the given file. This argument is mandatory when generating the ``dylib'' format. For other formats, by default the output is redirected to the standard output.

-hh, --hheellpp

Prints a summary of the options.

-dd, --ddeebbuugg

Turns on debugging messages. You probably don't want to enable this option, unless you are going to debug the metadata generator.

-vv, --vveerrssiioonn

Shows the version of the program. The version is also marked in gen-

erated metadata files, as the ``version'' attribute of the

``signatures'' top-level element.

EEXXAAMMPPLLEESS This generates bridge support metadata for a custom framework:

mkdir -p /Path/To/YourFramework.framework/Resources/BridgeSupport

genbridgemetadata -f /Path/To/YourFramework.framework -o

/Path/To/YourFramework.framework/Resources/BridgeSupport/YourFramework.bridgesupport If the custom framework has inline functions and you want to be able to call them, here is how you can generate a ``dylib'' file:

genbridgemetadata -f /Path/To/YourFramework.framework -F dylib -o

/Path/To/YourFramework.framework/Resources/BridgeSupport/YourFramework.dylib It is also possible to generate bridge support metadata for a standalone C library (here, libcurl):

genbridgemetadata -c '-lcurl -I/usr/include/curl'

/usr/include/curl/*.h > /Library/BridgeSupport/curl.bridgesupport