# apidiff

**Repository Path**: mirrors_openjdk/apidiff

## Basic Information

- **Project Name**: apidiff
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-08-14
- **Last Updated**: 2024-12-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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 running
`make/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 either
`make/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 APIDiff
[project page][apidiff-project]:

* ["man" page][apidiff-man]
* [command-line help][apidiff-cmdline-help]

[apidiff-project]: https://openjdk.org/projects/code-tools/apidiff/
[apidiff-man]: https://openjdk.org/projects/code-tools/apidiff/apidiff.html
[apidiff-cmdline-help]: https://openjdk.org/projects/code-tools/apidiff/cmdline-help.html

## ShowDocs

`showDocs` is a small utility program that is a simple wrapper around the
`APIReader` 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`.


[Daisy Diff]: https://github.com/DaisyDiff/DaisyDiff
[Equinox]: https://projects.eclipse.org/projects/eclipse.equinox
[HtmlCleaner]: https://htmlcleaner.sourceforge.net
[Java Diff Utils]: https://github.com/java-diff-utils/java-diff-utils
[JUnit]: https://junit.org/