7903799: apidiff: add initial code

Reviewed-by: iris

Author: jonathan-gibbons

.gitignore

@@ -0,0 +1,13 @@
+**.iml
+.DS_store
+.idea
+/.src-rev
+/build.properties
+attic
+build
+dist
+nbproject
+out
+play
+tmp
+webrev

CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# Contributing to APIDiff
+
+APIDiff is part of the OpenJDK [CodeTools] Project.
+
+Please see <https://openjdk.org/contribute/> for how to contribute.
+
+
+[CodeTools]: https://openjdk.org/projects/code-tools

COPYRIGHT

@@ -0,0 +1,20 @@
+Copyright (c) 1996, 2024, Oracle and/or its affiliates. All rights reserved.
+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+This code is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License version 2 only, as
+published by the Free Software Foundation.
+
+This code is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+version 2 for more details (a copy is included in the LICENSE file that
+accompanied this code).
+
+You should have received a copy of the GNU General Public License version
+2 along with this work; if not, write to the Free Software Foundation,
+Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+or visit www.oracle.com if you need additional information or have any
+questions.

LICENSE

@@ -0,0 +1,83 @@
+# APIDiff
+
+APIDiff is a utility to compare two or more versions of an API, each as
+defined by a series of options similar to those supported by `javac`.
+
+## Building `apidiff`
+
+`apidiff` uses the following dependencies:
+
+* _[Daisy Diff]_: an HTML comparison library, required when building `apidiff`
+* _[Java Diff Utils]_: a plain-text comparison library, required when building `apidiff`
+* _[TestNG]_: 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`.
+
+### Building with Apache Ant
+
+The default configuration assumes that dependencies have been downloaded
+into the `build/deps` directory.
+These values can be overridden with project-specific local configuration values
+in `build.properties`, if it exists in the root directory of the repo.
+
+````
+    ant -f make/build.xml <target>
+````
+
+### 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`.
+
+````
+    make -C make Makefile <target>
+````
+
+### Building with an IDE
+
+An IDE such as IntelliJ IDEA needs the following configuration:
+
+* Sources Root: `src`
+* TestNG Test Root: `test/testng`
+* Libraries:
+  * _Daisy Diff_, _Java Diff Utils_ available for compilation
+  * _TestNG_ available for testing
+
+In addition, some TestNG tests require access to internal classes in
+the `jdk.compiler` and `jdk.jdeps` modules:
+
+````
+--add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
+--add-exports jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED
+--add-modules jdk.jdeps
+--add-exports jdk.jdeps/com.sun.tools.classfile=ALL-UNNAMED
+````
+
+The following compiler options may also be desirable:
+
+````
+-Xdoclint:missing/protected
+-Xlint:unchecked
+````
+
+_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 
+for a module.
+
+## Documentation
+
+A "man" page is generated as part of the build, and is the primary source
+of information for how to run `apidiff`.
+
+## ShowDocs
+
+`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
+[Java Diff Utils]: https://github.com/java-diff-utils/java-diff-utils
+[TestNG]: https://testng.org/