objc-diff(1) Manual Page

NAME

objc-diff - generates an Objective-C API diff report

SYNOPSIS

objc-diff [--old <old-api-path>] --new <new-api-path> [options]

DESCRIPTION

objc-diff generates a text, XML, or HTML report of the API differences between two versions of an Objective-C library. It assists library authors with creating a diff report for their users and verifying that no unexpected API changes have been made.

Only the --new argument is required. If --old is ommitted all declarations in the API will be reported as additions. This supports generating a report for the first version of an API, and can also be used to review the API that the tool has parsed from the headers.

The paths to the old and new API versions can be specified in one of three ways:

1. Path to a framework

   If the library is distributed as a framework this is the most convenient option. The tool will parse the framework’s headers and automatically add the parent directory to the framework search paths so that import directives in the form of #import <FrameworkName/Header.h> can be resolved without additional configuration.

   If both API paths are frameworks with version information specified in their Info.plist the tool will also generate a report title automatically if no --title argument is provided.

2. Path to a specific header

   The header and all non-system headers that it includes will be considered part of the API.

3. Path to a directory of headers

   The directory will be searched recursively for header files. All header files found and all non-system headers they include will be considered part of the API.

4. Path to a platform SDK

   All frameworks in the SDK will be included in the API, with the following exceptions:

   • IOKit.framework
   • Kernel.framework
   • Tk.framework

   The contents of /usr/include are not included. A platform SDK can only be compared against another platform SDK.

Specifying Compiler Arguments

Parsing the API headers may require additional compiler arguments such as header search paths or preprocessor definitions. These are specified via the --args, --oldargs, and --newargs options. All arguments following one of these options up to the next objc-diff option or the end of the argument list are passed to the compiler, and follow the same form as the arguments accepted by clang(1).

When specifying search paths for additional dependencies that are not part of the API, use -isystem rather than -I. This will ensure that the declarations in these headers are excluded from the API.

OPTIONS

• --old <path>

  Path to the old API headers.

• --new <path>

  Path to the new API headers.

• --sdk <sdkname>

  The SDK to compile the headers against. May be specified as an absolute path or an SDK name in the same form accepted by xcrun(1) or xcodebuild(1). If not specified the latest OS X SDK will be used.

• --args <arguments>

  Compiler arguments to use for both API versions.

• --oldargs <arguments>

  Compiler arguments to use for the old API version.

• --newargs <arguments>

  Compiler arguments to use for the new API version.

• --title <title>

  The title to use for the report. If both API paths are frameworks that include version information in their Info.plist a title will be generated automatically if none is provided.

• --text

  Writes a text report to standard output. This is the default if no report format is specified.

• --xml

  Writes an XML report to standard output.

• --html <directory>

  Writes an HTML report to the specified directory.

EXAMPLES

Generate an HTML report for a framework:

objc-diff --old 1.0/Example.framework --new 1.1/Example.framework --html apidiff

Generate a text report for an iOS static library that uses import directives in the form of #import <Example/Header.h>:

objc-diff --sdk iphonesimulator --old 1.0/Example/Example.h --oldargs -I1.0 --new 1.1/Example/Example.h --newargs -I1.1  

Generate an XML report for the first version of an API:

objc-diff --new 1.0/Example.framework --xml

SEE ALSO

clang(1), xcrun(1)