GEN_BRIDGE_METADATA(1)       General Commands Manual      GEN_BRIDGE_METADATA(1)

     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 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

     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

          final                The final metadata format. This is the default

          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.

          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.

          This option has no effect. It is included for backwards compatibility,
          as 32-bit support is deprecated. Only 64-bit support exists.

          This option has no effect. It is included for backwards compatibility,
          as 32-bit support is deprecated. Only 64-bit support exists.

          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.

     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 > /Library/BridgeSupport/curl.bridgesupport

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

macOS 12.1                        May 24, 2010                        macOS 12.1