Native Image Committer and Community Meeting 2025-03-27

[wirthi]

List of all past and upcoming meetings: #3933

The meeting after this one is planned for April 24th, 2025. The meeting will typically be on the last Thursday of each month.

New and Noteworthy

JDK 24 has been released on March 18th. JDK 25 (next LTS) is expected for mid September 2025. Version number alignment between Java and GraalVM, finally :-)

• Native Image Layers
  [GR-60421] Implement package-wildcards for LayerCreate package suboption. #10756
  [GR-53530] Make static fields base support layer aware. #10824
  [GR-62614] Layered ImageHeapMap #10906
  [GR-62599] Sort fields by name and type. #10877
  [GR-62602] Throw consistent error type for unsafe accesses of static word fields #10853
  [GR-62799] Fix layers linker errors. #10816
  [GR-59256] Write missing constants in the application layer #10797
  [GR-62599] Sort fields by kind and name to ensure stable order. #10796
  [GR-62607] Fix JavaMainSupport.mainArgs. #10795
  [GR-62314] Register libraries from base layer in extension layers #10764

• GuestGraal / LibGraal
  [GR-62124] Remove jdk.graal.compiler dependency on org.graalvm.nativeimage. #10863
  [GR-62316] Reduce system property access in ImageInfo. #10833
  [GR-62769] Disable libgraal-specific API if it isn't needed. #10811
  [GR-62569] Libgraal needs jdk.graal.compiler.management. #10769

• Streamline reachability metadata

• Usability
  [GR-54953] Option -H:Preserve=all that preserves all classes, resources, and reflection metadata from a module, a package, or a classpath entry. #10180
  [GR-49525] Option '--future-defaults=<option>' to enable options that are planned to become defaults in future releases. #10531
  [GR-62624] Fix StaticProperty.javaHome to reflect user input. #10787

• Monitoring / tools
  Update remote JMX docs  #10774 (Red Hat)

• Debugging

• FFM API / Panama
  [GR-52573] Allow usage of foreign memory API on all platforms. #10890
  [GR-63069] Fix libffi warnings on Darwin #10865
  [GR-59770] [GR-62951] [GR-63030] Fixes for the NFI Panama backend #10859
  [GR-58659] [GR-58660] Add FFM Support for {darwin,linux}-aarch64 on SubstrateVM #10856
  [GR-52567] FFM API support for windows-amd64. #10788
  [GR-59770] Make PanamaNFILanguage load cleanly on JDK 21 #10746

• Remove JDK 21 from our master branch
  [GR-59050] Switched Truffle gates using native-image to downloaded GraalVM-21. #10786

• SBOM generation
  [GR-62929] Update docs: embed SBOM by default #10893

• Lazy Deoptimization (Internship)
  [GR-62522] Fix Deoptimization Issues #10818
  [GR-62080] Prevent out-of-memory errors during deoptimization #10741

• Other & fixes
  [GR-63018] Increase code alignment on AMD64 to 32 bytes. #10895
  [GR-62834] Native image should respect @jdk.internal.vm.annotation.DontInline #10875
  [GR-61347] [GR-62499] [GR-62610] [GR-62658] Various serial GC fixes and added option -XX:+PrintVMInfoAndExit. #10848
  [GR-62604] Suggest to use the next-to-be-released musl version. #10794
  [GR-63037] Cleanups and refactorings for STATUS_IN_VM. #10914
  [GR-62126] Reverse dependency between svm core and svm configure projects. #10905
  [GR-62810] Use CGlobalData base address from the heap in runtime-compiled code. #10901
  [GR-63033] [GR-63361] Add specialized filter primitive flow for constant y operand #10897

Questions

Deep Dive: Update on Layered Native Images

[cstancu]

Layered Native Image - Status Update

Goals:

• Enable incremental builds in Native Image
  • Build all dependencies in one or multiple shared objects
  • Automatically rebuild only a thin application image on change
• Enable run time sharing between apps
  • Build common dependencies in shared layers
  • Map shared layers with copy-on-write

---

The application and its supporting layers form a chain:

base-layer.so             # initial layer (includes VM/JDK code)
└── mid-layer.so          # intermediate layer, depends on base-layer.so, adds extra functionality 
    └── executable-image  # application image, depends on mid-layer.so and base-layer.so

When multiple applications share layers, they form a tree:

base-layer.so                    # initial layer (includes VM/JDK code)
├── executable-image-0           # application image, depends on base-layer.so
├── mid-layer-0.so               # intermediate layer, depends on base-layer.so
│   ├── executable-image-00      # application image, depends on mid-layer-0.so and base-layer.so
│   └── executable-image-01      # application image, depends on mid-layer-0.so and base-layer.so
└── mid-layer-1.so               # intermediate layer, depends on base-layer.so
    └── executable-image-10      # application image, depends on mid-layer-1.so and base-layer.so

---

Create a base layer for Micronaut

Args = -H:LayerCreate=@layer-create.args \
       -H:ApplicationLayerOnlySingletons= \
            io.micronaut.core.io.service.ServiceScanner$StaticServiceDefinitions

@layer-create.args:

base-layer.nil
module=java.base
package=io.micronaut.*
package=io.netty.*
package=jakarta.*
package=com.fasterxml.jackson.*
package=org.slf4j.*
package=reactor.*
package=org.reactivestreams.*

Alternative : module=libray-module, path=library.jar

Result of a layered build

[base-layer.nil]                  # shared layer archive file
  ├── base-layer.so               # shared object file; used by subsequent build and runtime
  ├── base-layer.lsb              # shared layer metadata; used by subsequent build processes
  ├── base-layer.big              # shared layer Graal graphs; used by subsequent build processes
  └── base-layer.properties       # contains info about layer input data

---

Use base-layer.nil for Micronaut app

Args = -H:LayerUse=../micronaut-base-layer-test/base-layer.nil \
       -H:LinkerRPath=$ORIGIN/libs

---

Invariants

• Every image build only creates one layer.

• Each layer can only depend on a previous layer

  • We explicitly make it impossible to depend on more than one layer to avoid multiple inheritance

• The image build command used to create the application layer must work without -H:LayerUse and create a standalone image.

  • The standalone command must completely specify the module/classpath and all other necessary configuration options

Layer compatibility

• The layer specified by -H:LayerUse must be compatible with the standalone command line, i.e.:

  • class/jar file compatibility (-cp, -p, same JDK, same GraalVM, same lib versios, etc.)
  • config compatibility: GC config, etc.
  • Java system properties and Environment variables compatibility

• Layers are platform dependent

  • A layer created with -H:LayerCreate on a specific OS/arch cannot be loaded by -H:LayerUse on a different OS/arch

• In case of incompatibility an error message is printed and the build process is aborted.

---

Limitations

• Currently supporting only 2 layers: base + application

• A shared layer is using the .so extension to conform with the standard OS loader restrictions.

  • However, it is not a standard shared library file, and it cannot be used with other applications

---

Programming model changes

• Managing static state needs to be layers-aware:

  • include it in base layer only
  • include it in app layer only
  • make it expand across layers

• For example framework caches can evolve across layers

  • io.micronaut.inject.annotation.AnnotationMetadataSupport

    private static final Map<String, Map<CharSequence, Object>> CORE_ANNOTATION_DEFAULTS;
    private static final Map<String, Map<CharSequence, Object>> ANNOTATION_DEFAULTS;
    private static final Map<String, String> REPEATABLE_ANNOTATIONS_CONTAINERS;
    private static final Map<String, String> CORE_REPEATABLE_ANNOTATIONS_CONTAINERS;

  • These caches collect metadata from both framework and application code
  • Solution: defer the field value to the application layer. That reduces sharing between layers.
    • User facing option: -H:DeferStaticFieldToApplicationLayer=<field-pattern>

• Singletons/Features need to be re-designed to accomodate multiple layers

  • Traditional singleton model: a key-value map whose lookups are constant folded within generated code
  • Layers-aware singleton model:
    • Top class: com.oracle.svm.core.layeredimagesingleton.LayeredImageSingleton
    • ApplicationLayerOnlyImageSingleton: ImageSingletons.lookup() calls refer to a singleton created in the app layer
    • MultiLayeredImageSingleton has APIs to access layered singletons:
      • T[] getAllLayers(Class<T> key) - get cross-layer singletons array for key
      • T getForLayer(Class<T> key, int index) - get specific layer singleton
    • InitialLayerOnlyImageSingleton: VM internal singletons
      • RuntimeInternedStrings, VMThreadLocalInfos, etc.
  • User facing option: -H:ApplicationLayerOnlySingletons=<fully-qualified-class-name>

• How to avoid static state issues: reduce the build time initialized code

Work in progress

• Native Build Tools support

  • First scenario: incremental rebuilds
    • Layers are (re)built transparently in the backround
    • The .so can be preserved and deployed with the application
  • Second scenario: Native Image Layer registry:
    • => app configuration (-cp, -mp, ni flags, etc.)
    • <= path/to/layer/archive.nil

• Making all Native Image features layer aware

  • E.g.: reflection config, Java module support

• Optimize layered build time

  • We are currently re-loading base layer metadata too eagerly

• Extensive testing to detect and fix all compatibility issues