Clarify build prerequisites and add a core build mode

[jvukicev]

What changed

The developer guide now distinguishes the JDK used to launch Gradle from the Java 17 toolchain required to compile Native Build Tools. Gradle may run on a newer supported JDK, including JDK 21 or 25, but a discoverable JDK 17 installation is still required. When Java 17 is unavailable, root configuration fails early with repository-specific guidance while retaining Gradle's underlying toolchain failure for diagnostics.

The root build also has a new opt-in core mode that omits the documentation composite before it is configured. Root lifecycle tasks aggregate every build selected by the active mode, and the default full build renders the AsciiDoc documentation.

Why

Developers using a newer launcher JDK could reasonably assume that no Java 17 installation was needed, then receive a delayed generic toolchain failure. Documentation dependencies were also configured even when a developer only needed the product builds, and root assemble did not actually assemble the included builds despite the developer guide saying it did.

The change makes the required toolchains explicit, provides a faster docs-independent feedback path, and makes the documented root lifecycle behavior match the task graph.

Example

Run the normal documentation-inclusive repository build:

./gradlew build

Run the product builds without configuring or rendering documentation:

./gradlew build -Porg.graalvm.build.core=true

The property is strict: absence or false selects the full build, true selects core mode, and any other value fails during settings evaluation.

Implementation summary

• Documented the separate Gradle launcher, discoverable Java 17 compiler toolchain, and GraalVM/native-image prerequisites.
• Added strict org.graalvm.build.core parsing and omitted docs during settings composition in core mode.
• Made root assemble, test, check, and inspections aggregate the builds present in the selected mode.
• Connected the default full root build to the documentation build and connected the documentation build lifecycle to asciidoctor.
• Added an early Java 17 toolchain prerequisite check using Gradle's public toolchain service, without enabling automatic provisioning.
• Added focused TestKit coverage for mode selection, malformed input, aggregation, documentation rendering, and the missing-JDK diagnostic.

Validation

The following checks passed:

• ./gradlew -p build-logic/aggregator cleanTest test --console=plain — 5 focused TestKit tests.
• ./gradlew -p build-logic/documentation-plugins cleanTest test --console=plain — 1 focused TestKit test with rendered AsciiDoc output.
• grund check
• grund fmt . --marker --cross-refs --check
• git diff --check
• ./gradlew help -Porg.graalvm.build.core=true --console=plain
• malformed-property smoke coverage for -Porg.graalvm.build.core=yes
• default full build --dry-run task-graph assertion containing :docs:asciidoctor and :docs:build
• core build --dry-run task-graph assertion containing product/common tasks and no :docs: tasks
• ./gradlew :native-gradle-plugin:inspections :native-maven-plugin:inspections -Porg.graalvm.build.core=true --console=plain
• constrained missing-JDK reproduction with toolchain auto-detection and auto-download disabled, confirming the actionable repository prerequisite message

A complete root ./gradlew build was not rerun because the existing :native-gradle-plugin:validatePlugins task reports unrelated Gradle 9.6.1 validation failures. Broad Native Image functional suites, the exact CI matrix, and documentation publication variants were not run locally.

Fixes #988

AI workflow

Generated by Rhei’s github-issue-fix workflow using 23 completed AI-assisted steps, 3 resolved models, and 3 focused review cycles. A maintainer-directed citation-only repair completed the blocked publication afterward.

View AI workflow details

Approved proposal: bbce876008d81808.

1. Issue intake and repository grounding

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: medium
Tokens: 738019 total · 726819 input (633472 cached) · 11200 output

Captured issue #988, repository rules, specifications, worktree metadata, and implementation scope.

2. Human proposal approval

Model: not applicable · Agent: human · Reasoning effort: not applicable
Tokens: not applicable

Approved proposal bbce876008d81808 for implementation.

3. Implement approved fix

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: medium
Tokens: 7082293 total · 7059553 input (6852608 cached) · 22740 output

Implemented the core/full build split, lifecycle aggregation, documentation rendering, developer guidance, specification updates, and focused TestKit coverage.

4. Validate implementation — visit 1

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: medium
Tokens: 2161957 total · 2149463 input (2060928 cached) · 12494 output

Ran focused tests, grounding checks, task-graph assertions, documentation rendering, and missing-toolchain reproduction.

5. Requirements review — cycle 1

Model: openai:gpt-5.6-terra · Agent: codex · Reasoning effort: medium
Tokens: 201905 total · 199426 input (164480 cached) · 2479 output

Identified that the Java-17-unavailable acceptance criterion needed an earlier repository-owned diagnostic or stronger evidence.

6. Spec review — cycle 1

Model: openai:gpt-5.6-terra · Agent: codex · Reasoning effort: medium
Tokens: 233051 total · 229794 input (190464 cached) · 3257 output

Checked specification order, repository grounding, and citation coverage with no blockers.

7. Implementation review — cycle 1

Model: openai:gpt-5.6-terra · Agent: codex · Reasoning effort: medium
Tokens: 217588 total · 213775 input (172672 cached) · 3813 output

Reviewed the initial implementation for scope, correctness, and regression coverage.

8. Validation review — cycle 1

Model: openai:gpt-5.6-terra · Agent: codex · Reasoning effort: medium
Tokens: 220063 total · 216368 input (180608 cached) · 3695 output

Accepted the focused validation while recording the missing-JDK evidence needed by requirements review.

9. Aggregate review — cycle 1

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: medium
Tokens: 129688 total · 127599 input (88320 cached) · 2089 output

Reconciled the specialist reviews and routed the missing-JDK diagnostic repair.

10. Address review findings — repair cycle 1

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: medium
Tokens: 1441840 total · 1432088 input (1358592 cached) · 9752 output

Added the early Java 17 prerequisite diagnostic, its specification, and constrained TestKit coverage.

11. Validate repaired implementation — visit 2

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: medium
Tokens: 949494 total · 937936 input (845312 cached) · 11558 output

Verified the new diagnostic, normal newer-JDK launcher behavior, focused tests, grounding, and task graphs.

12. Requirements review — cycle 2

Model: openai:gpt-5.6-terra · Agent: codex · Reasoning effort: medium
Tokens: 329495 total · 325266 input (288896 cached) · 4229 output

Confirmed the repaired implementation satisfied the issue acceptance criteria.

13. Spec review — cycle 2

Model: openai:gpt-5.6-terra · Agent: codex · Reasoning effort: medium
Tokens: 311804 total · 306415 input (257792 cached) · 5389 output

Found that the missing-JDK TestKit case lacked its most-specific specification citation.

14. Implementation review — cycle 2

Model: openai:gpt-5.6-terra · Agent: codex · Reasoning effort: medium
Tokens: 285318 total · 279309 input (234880 cached) · 6009 output

Confirmed implementation behavior and reported the same missing test citation blocker.

15. Validation review — cycle 2

Model: openai:gpt-5.6-terra · Agent: codex · Reasoning effort: medium
Tokens: 296967 total · 292549 input (257152 cached) · 4418 output

Accepted focused validation and documented the remaining broad validation gaps.

16. Aggregate review — cycle 2

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: medium
Tokens: 179869 total · 176620 input (132736 cached) · 3249 output

Reconciled cycle 2 and routed the missing citation repair.

17. Address review findings — repair cycle 2

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: medium
Tokens: 336319 total · 332173 input (300288 cached) · 4146 output

Added §FS-build-infrastructure.2.1 to the missing-Java-17 TestKit case.

18. Validate repaired implementation — visit 3

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: medium
Tokens: 1101052 total · 1086362 input (998144 cached) · 14690 output

Reran focused TestKit, grounding, task-graph, inspection, and missing-toolchain checks.

19. Requirements review — cycle 3

Model: openai:gpt-5.6-terra · Agent: codex · Reasoning effort: medium
Tokens: 323460 total · 319071 input (268416 cached) · 4389 output

Confirmed all issue requirements were satisfied.

20. Spec review — cycle 3

Model: openai:gpt-5.6-terra · Agent: codex · Reasoning effort: medium
Tokens: 383331 total · 377726 input (339072 cached) · 5605 output

Found two missing most-specific citations on the newly added TestKit dependency infrastructure.

21. Implementation review — cycle 3

Model: openai:gpt-5.6-terra · Agent: codex · Reasoning effort: medium
Tokens: 256480 total · 252708 input (216448 cached) · 3772 output

Found the new missing-toolchain citation comment placed between @Test and its declaration.

22. Validation review — cycle 3

Model: openai:gpt-5.6-terra · Agent: codex · Reasoning effort: medium
Tokens: 210758 total · 207037 input (174080 cached) · 3721 output

Accepted all focused validation with no blocking failures.

23. Aggregate review — cycle 3

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: medium
Tokens: 126767 total · 123858 input (100608 cached) · 2909 output

Reconciled the final review and recorded three fixable citation and placement blockers.

24. Record blocked publication

Model: openai:gpt-5.6-luna · Agent: codex · Reasoning effort: medium
Tokens: 87296 total · 85811 input (68480 cached) · 1485 output

Kept the branch local because the configured two repair visits were exhausted after the third review cycle.

25. Maintainer-directed final repair and publication

Model: not recorded by Rhei · Agent: codex · Reasoning effort: not reported
Tokens: not captured by Rhei accounting

Applied the three citation-only review fixes, reran the focused checks, committed the result, pushed graalvm:rhei/issue-988, and opened this ready-for-review PR.

Aggregate token usage: 17604814 total · 17457726 input (16184448 cached) · 147088 output

The aggregate covers all 23 finalized Rhei agent invocations and excludes the maintainer-directed final repair and publication. Deterministic program routing is non-model work. Focused review cycles: 3. Review-repair cycles: 2 within Rhei, followed by one citation-only completion. Accounting coverage: 23 measured Rhei invocations. Superseded attempts: none. Unmeasured Rhei attempts: none. Pricing: unpriced. Unsupported cache dimensions: input cache write, output cached read, and output cache write.