CodeTools proposal: apidiff

Fri Jan 8 21:01:20 UTC 2021

Hi Jonathan,

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 [1] or JapiCmp [2]
(which forms the basis of the AdoptOpenJDK JDK API Diff Report [3]). 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 [4]. Is this
proposal somehow related to this tool?

Thanks,

--Gunnar

[1] https://github.com/revapi/revapi
[2] https://github.com/siom79/japicmp
[3] https://github.com/AdoptOpenJDK/jdk-api-diff
[4] https://cr.openjdk.java.net/~mr/jigsaw/spec/diff/index.html

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
> versions
> 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
> developers
>    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]
> of
> 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
> and/or
> 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
> those
> 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][])
> are
> 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
> classes
> 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
> in
> 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"
> parts
> 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
> report.
> An internal component provides the ability to extract the parts of an API
> documentation file containing the specifications of the declarations in
> that
> file, ignoring the "window dressing" of the header, footer, and summary
> tables;
> 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
> [compatibility]:
> https://wiki.openjdk.java.net/display/csr/Kinds+of+Compatibility
> [binary compatible]:
> https://docs.oracle.com/javase/specs/jls/se15/html/jls-13.html
> [java-diff-utils]: https://github.com/java-diff-utils/java-diff-utils
> [daisydiff]: https://code.google.com/archive/p/daisydiff/
>
>
>
>