GEN_BRIDGE_METADATA(1)					    BSD 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 com-
     piler.  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 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:

     o	 /Library/Frameworks/MyFramework/Resources/BridgeSupport

     o	 /Library/BridgeSupport

     o	 ~/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 for-
			       mat. Once your exception file is finished you can pass it to the -e argument in order to generate the final meta-
			       data.

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

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

     --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 dur-
	  ing 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)

BSD
								   May 24, 2010 							       BSD