Typetools fork of the JDK
=========================

This fork of the JDK contains type annotations for pluggable type-checking.

It does *not* contain annotations for certain files (because annotations in
them cause build failures, especially in the interim builds):
 * the jdk.rmic module
 * objectweb/asm files
 * src/java.base/share/classes/java/time/*
 * src/jdk.compiler/share/classes/com/sun/tools/javac/*

Annotations for classes that exist in JDK 8 but were removed in JDK 11 appear
in jdk8.astub files in repository https://github.com/typetools/checker-framework/ .


Contributing
------------

We welcome pull requests that add new annotations or correct existing ones.
Thanks in advance for your contributions!

When adding annotations, please annotate an entire file at a time, and add an
`@AnnotatedFor` annotation on the class declaration.  The rationale is explained
at https://checkerframework.org/manual/#library-tips-fully-annotate .


Relationship to other repositories
----------------------------------

This fork is not up to date with respect to `openjdk/jdk` (the current OpenJDK version).
This fork contains all commits through the release of JDK 11:
https://github.com/typetools/jdk/commit/da75f3c4ad5bdf25167a3ed80e51f567ab3dbd01
with commit message:
8209806: API docs should be updated to refer to javase11

This fork is an ancestor of JDK release forks such as jdk11u.  This fork
does not compile, because the commit of `openjdk/jdk` on which it is based
no longer compiles, due to changes to tools such as compilers.
Repositories such as jdk11u and jdk12u have been updated and do compile.

This fork's annotations are pulled into those repositories, in order to
build an annotated JDK.  We do not write annotations in (say) jdk11u,
because it has diverged far from other repositories.  It would be even more
painful to write annotations on jdk11u and then try to merge it into a
subsequent version like jdk12u.


Pull request merge conflicts
----------------------------

If a pull request is failing with a merge conflict in `jdk11u`, first
update jdk11u from its upstreams, using the directions in section
"The typetools/jdk11u repository" below.

If that does not resolve the issue, then do the following in a clone of the
branch of `jdk` whose pull request is failing.

```
BRANCH=`git rev-parse --abbrev-ref HEAD`
URL=`git config --get remote.origin.url`
SLUG=${URL#*:}
ORG=${SLUG%/*}
JDK11DIR=../jdk11u-fork-$ORG-branch-$BRANCH
JDK11URL=`echo "$URL" | sed 's/jdk/jdk11u/'`
echo BRANCH=$BRANCH
echo URL=$URL
echo JDK11DIR=$JDK11DIR
echo JDK11URL=$JDK11URL
if [ -d $JDK11DIR ] ; then
  (cd $JDK11DIR && git pull)
else
  git clone $JDK11URL $JDK11DIR && (cd $JDK11DIR && (git checkout $BRANCH || git checkout -b $BRANCH))
fi
cd $JDK11DIR
git pull $URL $BRANCH
```

Manual step: resolve conflicts and complete the merge.

```
git push --set-upstream origin $BRANCH
```

Manual step: restart the pull request CI job.

After the pull request is merged to https://github.com/typetools/jdk,
follow the instructions at https://github.com/typetools/jdk11u to update
jdk11u, taking guidance from the merge done in the fork of jdk11u to
resolve conflicts.  Then, discard the branch in the fork of jdk11u.


Qualifier definitions
---------------------

The java.base module contains a copy of the Checker Framework qualifiers.
To update that copy, run from this directory:

(cd $CHECKERFRAMEWORK && rm -rf checker-qual/build/libs && ./gradlew :checker-qual:sourcesJar) && \
rm -f checker-qual.jar && \
cp -p $CHECKERFRAMEWORK/checker-qual/build/libs/checker-qual-*-sources.jar checker-qual.jar && \
(cd src/java.base/share/classes && rm -rf org/checkerframework && \
  unzip ../../../../checker-qual.jar -x 'META-INF*' && \
  rm -f org/checkerframework/checker/signedness/SignednessUtilExtra.java && \
  chmod -R u+w org/checkerframework) && \
jar tf checker-qual.jar | grep '\.java$' | sed 's/\/[^/]*\.java/;/' | sed 's/\//./g' | sed 's/^/    exports /' | sort | uniq

Copy the exports lines that were printed by the last command to
src/java.base/share/classes/module-info.java .
Commit the changes, including the changed top-level `checker-qual.jar` file.


The typetools/jdk11u repository
-------------------------------

The typetools/jdk11u repository is a merge of `openjdk/jdk11u` and `typetools/jdk`.
That is, it is a fork of `openjdk/jdk11u`, with Checker Framework type annotations.

**Do not edit the `typetools/jdk11u` repository.**
Make changes in the `typetools/jdk` repository.
(Note that this README file appears in both the `typetools/jdk` and `typetools/jdk11u` repositories!)

To update jdk11u from its upstreams:
```
cd jdk11u
git pull
git pull https://github.com/typetools/jdk11u.git
git pull https://github.com/openjdk/jdk11u.git
git pull https://github.com/typetools/jdk.git
```


Upstream README follows
-----------------------

The remainder of this file is the README from `openjdk/jdk`.


Welcome to the JDK!
===================

For information about building the JDK, including how to retrieve all
of the source code, please see either of these files:

  * doc/building.html   (html version)
  * doc/building.md     (markdown version)

See http://openjdk.java.net/ for more information about the OpenJDK
Community and the JDK.