objc-diff(1) Manual Page


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


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


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.



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


clang(1), xcrun(1)