Native Image Committer and Community Meeting 2025-04-24

[wirthi]

List of all past and upcoming meetings: #3933

The meeting after this one is planned for May 22nd, 2025 (29th is the public holiday in most of Europe). The meeting will typically be on the last Thursday of each month.

New and Noteworthy

• Native Image Layers
  [GR-57645] Support registering elements for reflection in extension layers #11056
  [GR-62109] Add directives to defer initialization to App Layer. #10963
  [GR-64145] Various Layer{Create,Use} option fixes. #11048
  [GR-62562] Skip methods not reachable in current layer from compilation. #11031
  [GR-61363] Shade CapnProto Runtime. #11020
  [GR-60530] Ensure layered static field state is initialized before queried. #10970

• GuestGraal / LibGraal
  [GR-64465] Removed org.graalvm.nativebridge dependency. #11053

• Streamline reachability metadata
  [GR-60238] Include JNI reachability metadata with reflection #11066

• Usability
  [GR-63280] [GR-63269] In the native-image output, format bytes plainly without fractions. #11002
  [GR-63098] Warn when image name starts with dash. #11001
  [GR-63551] Improve build-time validation of Native Image options. #10940
  [GR-62046] Support -H:+MetadataTracing with an empty configuration file. #10987
  [GR-64002] Internal ignore lists for -H:Preserve. #10982
  [GR-63998] Enable -H:Preserve=all on Windows. #11067
  [GR-63360] Ignore precomputed lambda forms from -H:Preserve=all #10932
  [GR-62629] Report user errors for huge relocatable objects in heap. #10960
  [GR-63457] Document system properties always included in a native image. #10943

• Monitoring / tools
  [GR-64420] Use initial system properties for jvmstat performance counters. #11049
  [GR-64209] Adopt attach API changes and fix @BasedOnJDKFile annotations. #11038
  [GR-63524] Fix class names in heap dumps. #10931

• Debugging
  [GR-63056] Fix jdwp crash when writing a class object array. #11032
  [GR-47973] Use correct hub size in debug info. #10999
  [GR-62990] Fields containing classes are not properly supported by the debug info. #10919

• FFM API / Panama
  [GR-60209] Implement new foreign configuration file syntax. #11023

• JDK Updates and removing JDK 21 from master
  [GR-64222] Adopt "JDK-8349988: Change cgroup version detection logic to not depend on /proc/cgroups" in libsvm_container #11043
  [GR-64209] Adopt attach API changes and fix @BasedOnJDKFile annotations. #11038
  [JDK-8354113] Adapt JDK-8351927: Change VirtualThread implementation to use use FJP delayed task handling #11013

• SBOM generation
  [GR-63227] Update SBOM BuildOutput.md, describe unassociated types #10934

• Other & fixes
  [GR-58673] Validate reachable object before propagating it. #11037
  [GR-64194] Invoke teardown hooks in Shutdown#exit substitution. #11034
  [GR-64109] SVM: Redundant computation in JavaThreads::getCurrentThreadId when assertion is off #11018
  [GR-62081] Fix TypeFlowGraph linearization #11012
  [GR-63262] SVM Serial: Emit imprecise write barriers for arrays in aligned heap chunks #11008
  [GR-64076] Fix heap dumping issues. #11006
  [GR-63494] [GR-63728] Simplify the safepoint code and only enable recurring callback support on demand. #10995
  [GR-34010] Change calculation of image heap huge threshold #10991 (Thomas Schrott)
  [GR-63733] Make Class.forName work with null caller class #10988
  [GR-63609] SVM: Optimize Serial GC write barriers of stores on newly created objects #10986
  [GR-63772] Fix serial GC write barrier verification. #10971
  [GR-63600] Fix missing optimization configs in benchmarks. #10961
  [GR-63723] Remove optimized hub access until compiler bug is fixed. #10952
  [GR-63337] Remove pointless parallel stream processing for classpath entries. #10920
  [GR-54022] Build first-object table and reset card table in compacting GC without an extra pass. #10933
  [GR-63366] [GR-63470] Refactor and cleanup the safepoint handling in Native Image. #10935
  [GR-62672] Refactorings for the identity hashcode support. #10936

Questions

Deep Dive: Advancing the Native Image Programming Model for Better Developer Experience

Goals

1. Require the least possible number of annotations (or JSON entries) without negatively affecting performance.
2. Provide a specification for Native Image development.
3. The semantics of Native Image should be executable in regular Java.
4. Make the developer experience straightforward--no complicated steps.

Streamline Reachability Metadata (Goal 1)

Based on: #7753

Introduce reachability-metadata.json: #9048
Include all metadata for reflection types: #9043
Include serialization metadata as part of reflection: #10215
Include JNI metadata as part of reflection: #11066
Remove superclass serialization constructor flag: #10213

Result:

{
  "reflection": [
    {
      "type": "fully.qualified.ClassName",
      "fields": [
        "name": "fieldName"
      ],
      "allPublicFields": true,
      "allDeclaredFields": true,
      "methods": [
        {
          "name": "methodName",
          "parameterTypes": [],
          "jniAccessible": true
        }
      ],
      "allPublicMethods": true,
      "allDeclaredMethods": true,
      "unsafeAllocated": true,
    }
  ],
  "resources": [
    {
      "glob": "ressource/path"
    }
  ],
  "bundles": [
    {
      "name": "resource.bundle.Name",
    }
  ],
  "serialization": [
    {
      "type": "fully.qualified.SerializableType",
      "customConstructorClass": "custom.constructor.Class"
    }
  ],
  "jni": [
    {
      "type": "fully.qualified.ClassName",
      "fields": [
        "name": "fieldName"
      ],
      "allPublicFields": true,
      "allDeclaredFields": true,
      "methods": [
        {
          "name": "methodName",
          "parameterTypes": [],
          "jniAccessible": true
        }
      ],
      "allPublicMethods": true,
      "allDeclaredMethods": true,
    }
  ]
}

To the simplified structure below:

{
  "reflection": [
    {
      "type": "fully.qualified.ClassName",
      "serializable": true,
      "jniAccessible": true,
      "unsafeAllocated": true,
      "allDeclaredFields": true,
      "methods": [
        {
          "name": "methodName",
          "parameterTypes": [],
        }
      ]
    }
  ],
  "resources": [
    {
      "glob": "ressource/path"
    },
    {
     "bundle": "resource.bundle.Name"
    }
  ]
}

Metadata Inference Specification (Goals 1, 2, and 3)

• [WIP][GR-45250][GR-45734] Reachability proofs for reflective operations #11079

--preserve=all (Goals 1 and 4)

• [GR-54953] Option -H:Preserve=all that preserves all classes, resources, and reflection metadata from a module, a package, or a classpath entry. #10180

Exact Metadata Tracing in Native Image with --preserve=all (Goal 4)

• [GR-62047] Trace all dynamic accesses from native image. #11081

Feature API for JDK Execution (Goala 3 and 4)

• [WIP][GR-62940] Introduce new API for metadata registration #11075

Putting it all Together: # Native Image Development Post JDK 25

• [GR-49525] Option '--future-defaults=<option>' to enable options that are planned to become defaults in future releases. #10531

All framework authors and users should switch to --future-defaults=all. The framework authors should test with this flag enabled.

Roles in Using Native Image

Library Author (LA) Needs to make sure all metadata is correctly present (even the negative lookups). For example, if their framework library looks for kotlin.Runtime, they need to have a metadata entry for that. If they would not do that, the end user would hit those issues and be unsatisfied.

End User (EU) Needs to make sure that only the metadata for things on the classpath are present. If a library author has missed the kotlin.Runtime lookup, they don't really care as long as they don't use Kotlin.

Execution Modes

Production: the image should run as good as possible even if some metadata entries are missed.
Initial run: the user wants to get metadata as easy as possible.
Development: the errors should interrupt users in case they miss metadata entries.
CI: we need to strictly verify that all the missing metadata is there.

Usage

Production

$ native-image [--pgo=<profiles>] [-O3] -jar <jar>

Initial Run

$ native-image --preserve=all [--pgo-instrument] -jar <program>
$ program -XX:RecordMetadata=<src>/META-INF/<group-id>

Development

Include extra flags when an error occurs.

Library or Framework Author

$ native-image [--exact-reachability-metadata] -jar <program>

End User

$ native-image [--debug-reachability-metadata] -jar <program>
$ program [-XX:MissingRegistrationReportMode=Exit]

Debugging Metadata

Library or Framework Author

$ native-image [--exact-reachability-metadata] -jar <program>

End User

$ native-image [--debug-reachability-metadata] -jar <program>
$ program [-XX:MissingRegistrationReportMode=Warn]

CI

Library Author

$ native-image --exact-reachability-metadata -jar <program>
$ program [-XX:MissingRegistrationReportMode=Exit]

End User

native-image --debug-reachability-metadata -jar <program>
program [-XX:MissingRegistrationReportMode=Exit]