apidiff (original) (raw)

APIDiff

APIDiff is a utility to compare two or more versions of an API, each as defined by a series of options similar to those supported by javac.

Building `apidiff`

apidiff uses the following dependencies:

Daisy Diff: an HTML comparison library, required when building apidiff
Equinox: the Eclipse Common Runtime, used by Daisy Diff; it is required when building Daisy Diff from source, but may already be included if using a precompiled copy of Daisy Diff in a JAR file.
HTMLCleaner : a library to sanitize HTML prior to comparison with Daisy Diff
Java Diff Utils: a plain-text comparison library, required when building apidiff
JUnit: the testing framework, used to run some of the tests for apidiff

Suitable versions of these dependencies can be downloaded by runningmake/build.sh, using configuration details in make/build-support/version-numbers.

Building with GNU Make

If you have run make/build.sh, there will be a convenient shell script stored in build/make.sh that runs make with variables set to the locations of the downloaded dependencies. You may also run make directly, using make variables to specify the locations of any necessary dependencies.

    sh build/make.sh <target>

Useful targets are:

sanity -- to check settings of necessary make variables,
build -- to build the files for a release, and
test -- to run all the available tests.

Building with an IDE

An IDE such as IntelliJ IDEA needs the following configuration:

Sources Root: src
JUnit Test Root: test/junit
Libraries:
- Daisy Diff, HTMLCleaner, Java Diff Utils available for compilation
- JUnit available for testing

Note: when working in an IDE, it is strongly recommended that you use a precompiled JAR file for Daisy Diff. The source files refer to additional dependencies that are not required or downloaded for APIDiff. While these source files are ignored when building APIDiff with GNU Make, it may not be possible to exclude those source files when registering Daisy Diff as a source-file dependency in the IDE.

In addition, some JUnit tests require access to internal classes in the jdk.compiler and jdk.jdeps modules:

--add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED
--add-modules jdk.jdeps
--add-exports jdk.jdeps/com.sun.tools.classfile=ALL-UNNAMED

The following compiler options may also be desirable:

-Xdoclint:missing/protected
-Xlint:unchecked

Note: When working on the test files, be careful not to mark module source directories as Test Sources Root at the same time as any source directories that are not for a module.

Testing `apidiff`

You can run the tests using the test target for GNU Make, using eithermake/build.sh or the subsequently generated build/make.sh. You can specify either the overall test target or the absolute path name of the *.ok file for any individual tests. That being said, most of the tests are written as JUnit tests, and can either be invoked as a group as part of the overall test target, or individually, by using JUnit directly, either using the JUnit command-line tool, or by using JUnit support within an IDE.

Just as some --add-exports options are needed to compile APIDiff, the same options will need to be provided in any IDE configuration used to run tests.

Documentation

A "man" page is generated as part of the build, and is the primary source of information for how to run apidiff. The tool also provides simple command-line help, listing the available options and a summary of their meaning.

You can see recent versions of the documentation on the APIDiffproject page:

ShowDocs

showDocs is a small utility program that is a simple wrapper around theAPIReader and SerializedFormReader classes in apidiff, that can provide filtered views of the files generated by javadoc, in order to view the parts of those files that will be compared by apidiff.