Skip to content

7903859: add more details to the top-level README.md file #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

7903859: add more details to the top-level README.md file #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 55 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <target>
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:
Expand All @@ -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:

Expand All @@ -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/
16 changes: 16 additions & 0 deletions src/share/doc/apidiff.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <module>/**`. If you want to compare the contents of
specific packages in a module, use `--include <module>/<package>.*`
or `--include <module>/<package>.**`. 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
Expand Down Expand Up @@ -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`.

Expand Down