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