gen_bridge_metadata
GEN_BRIDGE_METADATA(1) General Commands Manual GEN_BRIDGE_METADATA(1)
NAME
gen_bridge_metadata – Objective-C Bridges Metadata Generator
SYNOPSIS
gen_bridge_metadata [options...] headers...
DESCRIPTION
gen_bridge_metadata is a tool that generates bridging metadata information
for a given framework or set of headers. The Objective-C bridges supported
in Mac OS X, such as 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 complete,
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
elements 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 specified 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 x86_64 metadata files should be .bridgesupport.
The extension for arm64e metadata files should be .arm64e.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
following 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 framework. 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
frameworks. 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 functions. 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 metadata
format. The given exception file must conform to a certain format,
described in bridgeSupport(5). Exception files are manually written,
but you can generate a template by passing -F exceptions-template to
the generator.
--arm64e
Write arm64e annotations instead of x86_64 and compiles the dylib as
arm64e. If a dylib already exists at the output file path, a multi-
architecture file will be created. An arm64e slice will be added to an
x86_64 dylib. Conversely, if an arm64e dylib exists first, running the
generator without the --arm64e argument will add an x86_64 slice.
--64-bit
This option has no effect. It is included for backwards compatibility,
as 32-bit support is deprecated. Only 64-bit support exists.
--no-32-bit
This option has no effect. It is included for backwards compatibility,
as 32-bit support is deprecated. Only 64-bit support exists.
--no-64-bit
This option has no effect. It is included for backwards compatibility,
as 32-bit support is deprecated. Only 64-bit support exists.
-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 annotations.
-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
generated 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 ALSO
BridgeSupport(5) /System/Library/DTDs/BridgeSupport.dtd ruby(1) python(1)
macOS 12.1 May 24, 2010 macOS 12.1