Mac Developer Library Developer


This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.


     gen_bridge_metadata -- Objective-C Bridges Metadata Generator

     gen_bridge_metadata [options...] headers...

     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 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 gener-ated generated
     ated 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 argu-ments. arguments.
     ments. 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 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 following possible locations, in
     order of priority:

     •   /Library/Frameworks/MyFramework/Resources/BridgeSupport/Library/BridgeSupport~/Library/BridgeSupport

     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 manu-ally manually
          ally written, but you can generate a template by passing -F exceptions-template to the generator.

          (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 created 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.

          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.

          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

     -o, --output file
          Writes the output to the given file. This argument is mandatory when generating the ``dylib'' for-mat. format.
          mat. 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.

     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

     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

     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 >

     BridgeSupport(5) /System/Library/DTDs/BridgeSupport.dtd ruby(1) python(1)

BSD                              May 24, 2010                              BSD

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.