Skip to content

Expand and improve java.nio.*Buffer stubs: - #185

Merged
cpovirk merged 1 commit into
mainfrom
xbuffer
Nov 19, 2026
Merged

cpovirk merged 1 commit into
mainfrom
xbuffer

Conversation

@cpovirk

@cpovirk cpovirk commented Nov 12, 2026

Copy link
Copy Markdown
Collaborator
  • Add JSpecify annotations to the template used to generate those files during builds.
    • This includes adding @Nullable to the CharSequence parameter in each relevant CharBuffer.append overload.
  • Make our hard-coded ByteBuffer.java match the actual generated output.
  • Add hard-coded copies of the other *Buffer.java classes.
  • Add a test that ensures that we update those copies for new changes.

This should all have no practical impact on users of checkers that are lenient with unannotated code, but it could help users of strict checkers that call equals or append on *Buffer classes (besides ByteBuffer.equals, which we already had covered).

- Add JSpecify annotations to the template used to generate those files during builds.
  - This includes adding `@Nullable` to the `CharSequence` parameter in each relevant `CharBuffer.append` overload.
- Make our hard-coded `ByteBuffer.java` match the actual generated output.
- Add hard-coded copies of the other `*Buffer.java` classes.
- Add a test that ensures that we update those copies for new changes.

This should all have no practical impact on users of checkers that are lenient with unannotated code, but it could help users of strict checkers that call `equals` or `append` on `*Buffer` classes (besides `ByteBuffer.equals`, which we already had covered).
@cpovirk

cpovirk commented Nov 12, 2026

Copy link
Copy Markdown
Collaborator Author

The existing and new hard-coded files aren't necessary for tools that actually run this repo's full build process or even use a lighter-weight process that at least uses make gensrc. They're motivated entirely by our Google use case, in which we don't run any make command, and any similar hypothetical use cases. It would be fair for you to ask that I get netdpb to review them :)

The rest of this PR should be useful more generally.

@msridhar msridhar left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I only reviewed the template; it looks good to me

@cpovirk

cpovirk commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator Author

Thanks, I'll take it :) I just set Opus 5.5 (medium) to work on looking for potential traps in the Makefile changes. It has some things that we could tweak but that don't look too worrisome. I will probably at least remember this if we have trouble finding buried error messages in the future:

I reviewed HEAD (21217bbf086, "Expand and improve java.nio.*Buffer stubs"), focusing on the Makefile change in GensrcBuffer.gmk. I didn't run a build. I just read the new rule and the JDK make code around it.

It's fine for your purposes, and I'd land it. The only real trap is Windows builds (point 1 below).

What the new rule does

It adds one make target, a marker file in the generated-source folder (gensrc/java.base/java/nio/). That target depends on all 7 generated *Buffer.java files and on all 7 checked-in copies. When any of them changes, make reruns diff -u on each pair. If any pair differs, it prints the diffs and a cp command to fix things, then fails. The marker is only updated when every pair matches, so a failed check reruns on the next build.

Things I checked that are fine

  • The checked-in copies are never compiled. When the build finds the same file in more than one source folder, it keeps the first and drops the rest (JavaCompilation.gmk L368). The generated folder is listed first (Modules.gmk), so the generated version wins. This already applied to your old ByteBuffer.java. The new check is what keeps the copies honest.
  • Ordering: the target is added to the java.base source-generation step, and Java compilation waits for that step. So a mismatch fails the build before compiling, which is what you want.
  • The marker file causes no side effects. Putting _*.marker files in gensrc is an existing JDK convention (e.g., _cldr-gensrc.marker, _the.*.marker). src.zip only picks up .java files, and java.base doesn't copy .marker files as resources.
  • Your CI runs it. jspecify.yml runs make jdk on Linux, which includes this step.
  • DIFF, ECHO and TOUCH are standard variables in the build's config. NUMBER_TYPES covers all 7 types.
  • Side benefit: src.zip gets both the checked-in and generated copies of each file. The check guarantees they're identical, so it doesn't matter which one ends up in the zip.

Possible traps (in priority order)

  1. Windows builds would always fail. The tool that generates these files (Spp.java) ends lines with System.getProperty("line.separator"), which is CRLF on Windows. Your .gitattributes has * -text, so checkouts keep LF endings, and diff would report every line as different. This doesn't matter today because your Windows CI is disabled, but anyone building on Windows would hit it. Cheap fixes:
    • use $(DIFF) -u --strip-trailing-cr (GNU diff, which the build already requires in practice), or
    • wrap the rule in ifeq ($(call isBuildOs, windows), false).
  2. Upstream merges. Any upstream change to X-Buffer.java.template, or to X-Buffer-bin.java.template (which feeds ByteBuffer), will break the build after a merge until someone runs the printed cp. That's the intended behavior. It's worth a line in whatever notes you keep for doing openjdk merges, so nobody is surprised.
  3. The error message can get buried. The recipe prints the ERROR: and cp instructions after the diffs, which can run to thousands of lines. In a parallel build that output is mixed in with everything else. The "repeated here" summary at the end of a failed build won't show it either: that only repeats commands that write a failure log, and this recipe doesn't. Consider printing the error and cp lines before the diffs (or both before and after), and maybe sending them to >&2.
  4. Minor:
    • The new variables (PUBLIC_BUFFER_FILES, PUBLIC_BUFFER_CHECK_MARKER) share make's single global namespace. A JSPECIFY_ prefix would make a clash with a future upstream name impossible and would mark the block as fork-specific.
    • A short # JSpecify: comment on the block would help whoever resolves merge conflicts in this file later.

@cpovirk
cpovirk merged commit 8cc8594 into main Nov 19, 2026
8 checks passed
@cpovirk
cpovirk deleted the xbuffer branch November 19, 2026 13:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants