objc-diff(1) Manual Page
objc-diff - generates an Objective-C API diff report
--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.
--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:
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
--titleargument is provided.
Path to a specific header
The header and all non-system headers that it includes will be considered part of the API.
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.
Path to a platform SDK
All frameworks in the SDK will be included in the API, with the following exceptions:
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
--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.
Path to the old API headers.
Path to the new API headers.
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.
Compiler arguments to use for both API versions.
Compiler arguments to use for the old API version.
Compiler arguments to use for the new API version.
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.
Writes a text report to standard output. This is the default if no report format is specified.
Writes an XML report to standard output.
Writes an HTML report to the specified directory.
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