CodeTools proposal: apidiff
gunnar at hibernate.org
Fri Jan 8 21:01:20 UTC 2021
That's a very interesting proposal, I've been missing some sort of API diff
tool in the JDK for a long time.
It sounds as if you already have a version of this tool working; could you
perhaps share an example for the kind of report it generates? I'd also be
curious how this differs from existing tools like RevApi  or JapiCmp 
(which forms the basis of the AdoptOpenJDK JDK API Diff Report ). There
also used to be a tool internally at Oracle which was (or maybe still is)
used for generating API diffs for JSR spec APIs, e.g. see . Is this
proposal somehow related to this tool?
Am Fr., 8. Jan. 2021 um 19:57 Uhr schrieb Jonathan Gibbons <
jonathan.gibbons at oracle.com>:
> On 1/8/21 10:48 AM, Jonathan Gibbons wrote:
> > This is a proposal for a new tool in the OpenJDK CodeTools project:
> > apidiff.
> > I've attached Markdown and HTML versions of the proposal.
> > -- Jon
> I guess the attachments didn't make it. Here's the Markdown:
> # Proposal: apidiff
> Summary: A utility to compare two or more versions of an API, using a
> combination of the information in class files, source files and/or API
> documentation files.
> ## Rationale
> An important task when evolving APIs is to be able to compare different
> of an API, such as before and after a proposed change. However, comparing
> versions of an API is not an easy task:
> * Comparing just source files is hard because of additional content
> related to
> the implementation of the API.
> * Comparing just class files is hard because class files do not include any
> narrative specification from the documentation comments.
> * Comparing just API documentation files is hard because the underlying
> model of
> the API can be difficult to discern, and is subject to the
> presentation by the
> `javadoc` tool. However, this is the form most commonly used by
> wanting to read the specification of an API.
> In addition, the Java language is [evolving][amber], with new features like
> [records] and [sealed classes], and it is desirable for comparison
> tools to
> be able to handle such features when they show up in an API.
> It would also be good to be able to classify changes with respect to
> whether or
> not they are compatible changes, and if so, what ["kind"][compatibility]
> compatible. However, this generally requires detailed and accurate
> models of the
> APIs being compared: more so than can reasonably be obtained from API
> documentation files.
> ## Description
> `apidiff` is a tool that leverages the `javac` front end and other code
> in the
> JDK `java.compiler` and `jdk.compiler` modules in order to read source
> class files, and to find the declarations to be compared. When source
> files are
> provided, the tool can also compare the "raw" documentation comments for
> declarations, and if the corresponding API documentation is provided,
> the tool
> can also extract and compare the parts of the documentation for those
> declarations. Third-party libraries ([java-diff-utils], [daisydiff])
> used to compare the plain text of documentation comments and the
> relevant parts
> of the generated API documentation.
> The tool can compare two or three versions of an API. It can compare
> on the class path, or in modules. It can also compare the often-overlooked
> specifications of the serialized forms of classes. It can compare classes
> different versions of JDK, although there are currently limitations if
> preview features are involved. The tool requires JDK 11 or newer to run:
> because it uses JDK modules internally, the tool must be run with a version
> of JDK at least as new as the newest API being compared.
> When comparing more than two versions of an API, the "structural" parts of
> each declaration are compared and reported as a group; the "narrative"
> of the specification of each declaration are compared pair-wise against the
> latest version.
> Internally, the tool comprises a front end, which can set up and access
> different concurrent instances of the `javac` front end and which reports
> differences via an interface to a back end, which can generate an HTML
> An internal component provides the ability to extract the parts of an API
> documentation file containing the specifications of the declarations in
> file, ignoring the "window dressing" of the header, footer, and summary
> this component can handle the output generated by most recent versions
> of the
> `javadoc` tool.
> [amber]: https://openjdk.java.net/projects/amber/
> [records]: https://openjdk.java.net/jeps/395
> [sealed classes]: https://openjdk.java.net/jeps/360
> [binary compatible]:
> [java-diff-utils]: https://github.com/java-diff-utils/java-diff-utils
> [daisydiff]: https://code.google.com/archive/p/daisydiff/
More information about the code-tools-dev