diff --git a/README.md b/README.md index 87c12f8..665f4f7 100644 --- a/README.md +++ b/README.md @@ -8,21 +8,33 @@ defined by a series of options similar to those supported by `javac`. `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`. +`make/build.sh`, using configuration details in `make/build-support/version-numbers`. ### Building with GNU Make -The default configuration uses values provided in `make/dependencies.gmk`, -unless these values have been overridden on the command line used to run `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. ```` - make -C make Makefile + sh build/make.sh ```` +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: @@ -33,6 +45,13 @@ An IDE such as IntelliJ IDEA needs the following configuration: * _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: @@ -51,22 +70,51 @@ The following compiler options may also be desirable: ```` _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 +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`. +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 +`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/ diff --git a/src/share/doc/apidiff.md b/src/share/doc/apidiff.md index 1003a8c..023dd84 100644 --- a/src/share/doc/apidiff.md +++ b/src/share/doc/apidiff.md @@ -349,6 +349,13 @@ although that is not a requirement. To eliminate any false positive differences being introduced by changes to the `javadoc` tool itself, the same or equivalent versions of `javadoc` should be used for each API to be compared. +If you want to compare all the exported packages in a module, use +`--include /**`. If you want to compare the contents of +specific packages in a module, use `--include /.*` +or `--include /.**`. The `.**` form will also include +the contents of any subpackages. You can use multiple `--include` +options to include different parts of an API in the comparison. + ### Configuring instances of JDK to be compared `apidiff` can be used to compare different instances of JDK, but that can be @@ -420,6 +427,15 @@ you can combine the recommended options for the two modes, specifying both `--patch-module` options for the source files and `--api-directory` for the generated documentation. +If you are using the `--jdk-build` option, and the corresponding `images` +directory has multiple matches for `images/*docs*`, you will need to use +the `--jdk-docs` option to disambiguate which documentation directory to use. +The value that you give should be the name of one of those subdirectories +of the `images` directory. The `--jdk-docs` option is not specific to any +individual API, and need only be given once on the command-line. +It will be used as needed to disambiguate the documentation directory to be +used for any API that is defined by using the `--jdk-build` option. + If you want to see or understand how the options are used internally, you can use `--verbose options`, possibly implicitly as part of `--verbose all`.