From jonathan.gibbons at oracle.com Fri Jan 8 18:48:24 2021 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 8 Jan 2021 10:48:24 -0800 Subject: CodeTools proposal: apidiff Message-ID: 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 From jonathan.gibbons at oracle.com Fri Jan 8 18:55:25 2021 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 8 Jan 2021 10:55:25 -0800 Subject: CodeTools proposal: apidiff In-Reply-To: References: Message-ID: <2ab29813-3057-1f84-b163-d2a0fa4dae20@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/ From gunnar at hibernate.org Fri Jan 8 21:01:20 2021 From: gunnar at hibernate.org (Gunnar Morling) Date: Fri, 8 Jan 2021 22:01:20 +0100 Subject: CodeTools proposal: apidiff In-Reply-To: <2ab29813-3057-1f84-b163-d2a0fa4dae20@oracle.com> References: <2ab29813-3057-1f84-b163-d2a0fa4dae20@oracle.com> Message-ID: 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/ > > > > From jonathan.gibbons at oracle.com Fri Jan 8 21:18:31 2021 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 8 Jan 2021 13:18:31 -0800 Subject: CodeTools proposal: apidiff In-Reply-To: References: <2ab29813-3057-1f84-b163-d2a0fa4dae20@oracle.com> Message-ID: <484155a2-b054-2402-9af2-97c5de7a183c@oracle.com> Hi Gunnar, Yes, I agree that some sort of JDK diff tool has been a long time coming, and yes, I have an advanced prototype that I hope to publish soon to a new GitHub repo under the "Code Tools" umbrella. Although I'm not an expert on many of the existing tools, my understanding is that they typically just compare class files, or compare javadoc output. `apidiff` is different because it can leverage a combination of inputs, and because it uses the `javac` front end to read source and class files, the tool will be easier to keep current with the latest JDK enhancements, especially when those enhancements involve new language features, new class features and/or revisions to the javadoc-generated documentation files. You are also correct that there has been an internal tool used to generate API diffs for JSR spec APIs. This proposal is related in the sense that the intent is to provide a public tool that can fulfill the same purpose. Indeed, this purpose is one of the reasons to support 3-way comparisons, so that we can routinely create reports of differences in the current build against the previous build and the previous GA build. You can sometimes also see evidence of that internal tool in CSR requests, and that is another intended use case for the new tool. -- Jon On 1/8/21 1:01 PM, Gunnar Morling wrote: > 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 > >: > > 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/ > > > > From kusrinivasan at vmware.com Fri Jan 15 18:05:42 2021 From: kusrinivasan at vmware.com (Kumar Srinivasan) Date: Fri, 15 Jan 2021 18:05:42 +0000 Subject: CodeTools proposal: apidiff In-Reply-To: <2ab29813-3057-1f84-b163-d2a0fa4dae20@oracle.com> References: <2ab29813-3057-1f84-b163-d2a0fa4dae20@oracle.com> Message-ID: +1 The old internal tool was far from optimal. Kumar > On Jan 8, 2021, at 10:55 AM, Jonathan Gibbons wrote: > > 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://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fopenjdk.java.net%2Fprojects%2Famber%2F&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=wg1UC1WLaEIdzpy%2Fka0FSVUHI%2Fo8TnL5hRQE%2FQdLPYM%3D&reserved=0 > [records]: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fopenjdk.java.net%2Fjeps%2F395&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=W81DltVfSDBzoIqaz71mHpLAd1%2BJRRaaNaDyiKLe8pU%3D&reserved=0 > [sealed classes]: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fopenjdk.java.net%2Fjeps%2F360&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=jmq%2FHLf2psdCtl5apyObExF2zw0crouYCDkaO1nMYEs%3D&reserved=0 > [compatibility]: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.openjdk.java.net%2Fdisplay%2Fcsr%2FKinds%2Bof%2BCompatibility&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=InfwdTKQvGsN%2BN06EuoAOSI373Giyn%2FZbfuxvI6XSjo%3D&reserved=0 > [binary compatible]: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdocs.oracle.com%2Fjavase%2Fspecs%2Fjls%2Fse15%2Fhtml%2Fjls-13.html&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=CrMmKF2rssvLU5ofpd3fZdE%2BOXuFcD%2BlVrAPTKg82UA%3D&reserved=0 > [java-diff-utils]: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fjava-diff-utils%2Fjava-diff-utils&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=sxQZIyWCmbHuT8bCcFSf1uEHrs5w9MBFdrpDqqyGDp0%3D&reserved=0 > [daisydiff]: https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fcode.google.com%2Farchive%2Fp%2Fdaisydiff%2F&data=04%7C01%7Ckusrinivasan%40vmware.com%7Ccabf1cb638f84db6886e08d8b4070f29%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637457289707078419%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=yjKHnQMegNUq5%2Bi4BTqX43t%2BqSRUfbpa0dZyGO3%2BzOI%3D&reserved=0 > > > From jonathan.gibbons at oracle.com Sat Jan 16 01:19:08 2021 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 15 Jan 2021 17:19:08 -0800 Subject: CodeTools proposal: apidiff In-Reply-To: References: <2ab29813-3057-1f84-b163-d2a0fa4dae20@oracle.com> Message-ID: <0667a625-b29e-5d1e-5dec-e939fd4c94ad@oracle.com> I'll be asking the OpenJDK admins next week to set up a repo for this. -- Jon On 1/15/21 10:05 AM, Kumar Srinivasan wrote: > +1 > > The old internal tool was far from optimal. > > Kumar > > >> On Jan 8, 2021, at 10:55 AM, Jonathan Gibbons wrote: >> >> 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://urldefense.com/v3/__https://nam04.safelinks.protection.outlook.com/?url=https*3A*2F*2Fopenjdk.java.net*2Fprojects*2Famber*2F&data=04*7C01*7Ckusrinivasan*40vmware.com*7Ccabf1cb638f84db6886e08d8b4070f29*7Cb39138ca3cee4b4aa4d6cd83d9dd62f0*7C0*7C0*7C637457289707078419*7CUnknown*7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0*3D*7C1000&sdata=wg1UC1WLaEIdzpy*2Fka0FSVUHI*2Fo8TnL5hRQE*2FQdLPYM*3D&reserved=0__;JSUlJSUlJSUlJSUlJSUlJSUlJSUlJQ!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9OIqo7hjQ$ >> [records]: https://urldefense.com/v3/__https://nam04.safelinks.protection.outlook.com/?url=https*3A*2F*2Fopenjdk.java.net*2Fjeps*2F395&data=04*7C01*7Ckusrinivasan*40vmware.com*7Ccabf1cb638f84db6886e08d8b4070f29*7Cb39138ca3cee4b4aa4d6cd83d9dd62f0*7C0*7C0*7C637457289707078419*7CUnknown*7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0*3D*7C1000&sdata=W81DltVfSDBzoIqaz71mHpLAd1*2BJRRaaNaDyiKLe8pU*3D&reserved=0__;JSUlJSUlJSUlJSUlJSUlJSUlJQ!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9P64C7t7g$ >> [sealed classes]: https://urldefense.com/v3/__https://nam04.safelinks.protection.outlook.com/?url=https*3A*2F*2Fopenjdk.java.net*2Fjeps*2F360&data=04*7C01*7Ckusrinivasan*40vmware.com*7Ccabf1cb638f84db6886e08d8b4070f29*7Cb39138ca3cee4b4aa4d6cd83d9dd62f0*7C0*7C0*7C637457289707078419*7CUnknown*7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0*3D*7C1000&sdata=jmq*2FHLf2psdCtl5apyObExF2zw0crouYCDkaO1nMYEs*3D&reserved=0__;JSUlJSUlJSUlJSUlJSUlJSUlJQ!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9MX9FDCtw$ >> [compatibility]: https://urldefense.com/v3/__https://nam04.safelinks.protection.outlook.com/?url=https*3A*2F*2Fwiki.openjdk.java.net*2Fdisplay*2Fcsr*2FKinds*2Bof*2BCompatibility&data=04*7C01*7Ckusrinivasan*40vmware.com*7Ccabf1cb638f84db6886e08d8b4070f29*7Cb39138ca3cee4b4aa4d6cd83d9dd62f0*7C0*7C0*7C637457289707078419*7CUnknown*7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0*3D*7C1000&sdata=InfwdTKQvGsN*2BN06EuoAOSI373Giyn*2FZbfuxvI6XSjo*3D&reserved=0__;JSUlJSUlJSUlJSUlJSUlJSUlJSUlJSU!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9NUTDlw2w$ >> [binary compatible]: https://urldefense.com/v3/__https://nam04.safelinks.protection.outlook.com/?url=https*3A*2F*2Fdocs.oracle.com*2Fjavase*2Fspecs*2Fjls*2Fse15*2Fhtml*2Fjls-13.html&data=04*7C01*7Ckusrinivasan*40vmware.com*7Ccabf1cb638f84db6886e08d8b4070f29*7Cb39138ca3cee4b4aa4d6cd83d9dd62f0*7C0*7C0*7C637457289707078419*7CUnknown*7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0*3D*7C1000&sdata=CrMmKF2rssvLU5ofpd3fZdE*2BOXuFcD*2BlVrAPTKg82UA*3D&reserved=0__;JSUlJSUlJSUlJSUlJSUlJSUlJSUlJSUl!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9NpwKYOIA$ >> [java-diff-utils]: https://urldefense.com/v3/__https://nam04.safelinks.protection.outlook.com/?url=https*3A*2F*2Fgithub.com*2Fjava-diff-utils*2Fjava-diff-utils&data=04*7C01*7Ckusrinivasan*40vmware.com*7Ccabf1cb638f84db6886e08d8b4070f29*7Cb39138ca3cee4b4aa4d6cd83d9dd62f0*7C0*7C0*7C637457289707078419*7CUnknown*7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0*3D*7C1000&sdata=sxQZIyWCmbHuT8bCcFSf1uEHrs5w9MBFdrpDqqyGDp0*3D&reserved=0__;JSUlJSUlJSUlJSUlJSUlJSUl!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9MJUKeIoA$ >> [daisydiff]: https://urldefense.com/v3/__https://nam04.safelinks.protection.outlook.com/?url=https*3A*2F*2Fcode.google.com*2Farchive*2Fp*2Fdaisydiff*2F&data=04*7C01*7Ckusrinivasan*40vmware.com*7Ccabf1cb638f84db6886e08d8b4070f29*7Cb39138ca3cee4b4aa4d6cd83d9dd62f0*7C0*7C0*7C637457289707078419*7CUnknown*7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0*3D*7C1000&sdata=yjKHnQMegNUq5*2Bi4BTqX43t*2BqSRUfbpa0dZyGO3*2BzOI*3D&reserved=0__;JSUlJSUlJSUlJSUlJSUlJSUlJSUlJSU!!GqivPVa7Brio!MK7sjebs9QhgwNCaGIBS4zmyXaVUIkbxQDCORCRfQWr6Hr3FcuSRTcntgfE4u9Mt4ccBpA$ >> >> >>