GEN_BRIDGE_METADATA(1) BSD General Commands Manual GEN_BRIDGE_METADATA(1)NAMEgen_bridge_metadata — Objective-C Bridges Metadata Generator
SYNOPSISgen_bridge_metadata [options...] headers...
DESCRIPTIONgen_bridge_metadata 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 MacRuby (Ruby) and PyObjC (Python), read
this information at runtime.
As of Mac OS 10.7, gen_bridge_metadata uses an improved parser, based on
clang. This means the generated files should be more correct and com‐
plete, and the true parsing allows the automatic extraction of metadata
from existing __attribute__() information supported by the compiler.
File generation time should also be faster.
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 gen_bridge_metadata tool
can then read in the exceptions file when it generates the framework
metadata.
The file extension used for metadata files should be .bridgesupport.
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 gen_bridge_metadata tool can take
care of that for you.
The file extension for the dynamic libraries should be .dylib.
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:
· /Library/Frameworks/MyFramework/Resources/BridgeSupport
· /Library/BridgeSupport
· ~/Library/BridgeSupport
OPTIONS
The gen_bridge_metadata tool accepts the following command-line options:
-f framework, --framework 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.
-p, --private
Generates metadata based on the private headers of the given frame‐
works. This argument must be used with the -f argument.
-F format, --format 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 -o 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 -e argument in order to generate the final
metadata.
-e file, --exception 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 -F
exceptions-template to the generator.
--64-bit
(This option is included for backwards compatibility, as this is now
the default behavior.) Writes both 32 and 64-bit annotations to the
final metadata format and compiles the dylib both 32 and 64-bit (if
a framework is specified and it only contains either 32 or 64-bit
architectures, then the final metadata format and dylib will be cre‐
ated only for that architecture). 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 both 32 and 64-bit will need
to be processed and merged into one.
--no-32-bit
Do not write the 32-bit annotations to the final metadata format or
compile the dylib 32-bit. May not be used with --no-64-bit.
--no-64-bit
Do not write the 64-bit annotations to the final metadata format or
compile the dylib 64-bit. May not be used with --no-32-bit.
-c, --cflags 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).
-C, --cflags-64 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.
-o, --output 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.
-h, --help
Prints a summary of the options.
-d, --debug
Turns on debugging messages. You probably don't want to enable this
option, unless you are going to debug the metadata generator.
-v, --version
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.
EXAMPLES
This generates bridge support metadata for a custom framework:
mkdir -p /Path/To/YourFramework.framework/Resources/BridgeSupport
gen_bridge_metadata-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:
gen_bridge_metadata-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):
gen_bridge_metadata-c '-lcurl -I/usr/include/curl'
/usr/include/curl/*.h > /Library/BridgeSupport/curl.bridgesupport
SEE ALSOBridgeSupport(5) /System/Library/DTDs/BridgeSupport.dtd ruby(1)python(1)BSD May 24, 2010 BSD
