GraalVM Native Image Agent: A Deep Dive

Dec 10, 2025 by Admin 40 views

Hey guys! So, you're diving into the awesome world of GraalVM Native Image, and you're hitting a snag with the agent not generating the necessary META-INF/native-image stuff. Don't sweat it! It's a common stumbling block, and while the native-maven-plugin is super powerful, its documentation can sometimes feel like trying to decipher ancient hieroglyphs. I've been there, spent ages with Maven and Graal Native Images, even contributed to bug reports, so I get it. Let's break down this agent issue and get you sorted.

The Documentation Dilemma: Bridging the Gap

First off, let's talk documentation. The plugin itself is fantastic, seriously! The way it leverages Maven profiles is brilliant for managing complex builds. But here's the rub: the docs sometimes feel a bit scattered. It's like getting snippets from a manual mixed with a 'learn-by-doing' approach, but without a complete, cohesive example to tie it all together. This means you're constantly jumping between sections, trying to piece together how a certain feature, like the agent, actually works in practice. We need clear, actionable examples that show the plugin features, especially with those handy skip options. While profiles are incredibly powerful for optimizing larger projects, a solid understanding of the core plugin mechanics should come first.

Think about established Maven plugin documentation standards, guys. They usually provide a clear path. This plugin's documentation, while informative, could benefit from that structured approach. Showing how to enable features and configure them within the <configuration> block, rather than just referencing them, would be a massive help. I know nothing's perfect, and I've definitely put my fair share of code out there (shout out to my projects like jarwalker, jain-slee-js, graaljs-autobox, and my current work on graalson, graalson-trax, and json-transformer), but when you're trying to get a specific piece of tech working, clear docs are gold.

The Core Problem: Agent Not Hooking In

So, the main headache is that the exec goal isn't picking up the Graal agent from the native-maven-plugin as expected. You know the agent should be creating a native-image directory in your target folder, which you then need to copy to src/main/resources/META-INF for the actual native-image compilation. You get how agents work in Java (--javaagent:), but you're unsure how this translates to the exec goal, especially when it's running in a forked process.

When you run mvn -X test, you're looking for that agent to be loaded automatically, or wondering if you need to explicitly add the jvmArgs to the exec plugin. For build tools like Surefire, it's more straightforward, but the exec plugin operates in its own isolated JVM. It feels like you're missing a conceptual piece of the puzzle here, and the documentation isn't quite illuminating it.

Investigating the Agent Mojo

I did a quick mvn help:describe -Dplugin=org.graalvm.buildtools:native-maven-plugin -Dfull to see if there was an obvious configure-agent mojo, but nothing jumped out. This suggests the agent integration might be more implicit or handled differently than a direct mojo call.

Documentation Duplication and Confusion

Another point of confusion arises from the documentation itself. I noticed a duplication error in the XML fragments provided for plugin configurations. Two sections appear identical, and then there's a reference to exec:exec@native, which isn't clearly defined or present in the preceding configurations. Is this my own mix-up, or is there a missing piece in how these configurations should be structured within the pom.xml?

Understanding Agent Integration with `exec-maven-plugin`

The key takeaway here is understanding how the native-maven-plugin is supposed to inject the agent into the execution of another plugin, like exec-maven-plugin. The documentation points to the <agent/> configuration within the native-maven-plugin block. This is where you define how the agent should be set up. When the native-maven-plugin prepares for a native image build, it should be able to leverage this configuration to attach the agent to subsequent Java processes, including those launched by exec-maven-plugin.

Let's look at the command line output you provided:

[DEBUG] Executing command line: [java, -classpath, ..., JsonT, test-classes/template.js, test-classes/ALL_FINES.json, all_fines_nsw.json, UTF8]

Notice that there's no -agentlib:native-image-agent flag here. This is the smoking gun! The agent isn't being automatically attached by the exec-maven-plugin in this context because the native-maven-plugin hasn't configured it to do so for this specific execution.

The Manual Fix (and Why It's Not Ideal)

You found a workaround by manually adding the agent argument to the exec-maven-plugin configuration:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>
    <version>3.0.0</version>
    <executions>
        <execution>
            <id>java-agent</id>
            <goals>
                <goal>exec</goal>
            </goals>
            <phase>test</phase>
            <configuration>
                <executable>java</executable>
                <workingDirectory>${project.build.directory}</workingDirectory>
                <arguments>
                    <argument>-agentlib:native-image-agent=config-output-dir=${basedir}/target/native-image/</argument>
                    <argument>-classpath</argument>
                    <classpath/>
                    <argument>${mainClass}</argument>
                </arguments>
            </configuration>
        </execution>
    </executions>
</plugin>

This works, and it's great that you figured it out! It confirms that the agent can be loaded. However, the goal is to use the <agent/> configuration within the native-maven-plugin itself, so that the plugin manages the agent attachment automatically. Relying on manual configuration in every plugin that needs the agent defeats the purpose of having a centralized agent configuration mechanism.

Leveraging the `<agent/>` Configuration Correctly

The native-maven-plugin's <agent/> configuration is designed to centralize the agent setup. When you define it, you're telling the plugin how to prepare the Java environment for agent-based analysis. The plugin is supposed to intercept relevant build steps and inject the agent arguments.

Let's look at how the <agent/> configuration should ideally be set up. It typically resides within the <configuration> block of the native-maven-plugin itself:

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>YOUR_VERSION</version> <!-- Use the latest stable version -->
    <configuration>
        <skipNativeImage>true</skipNativeImage> <!-- Example: Only use agent for now -->
        <agent>
            <enabled>true</enabled>
            <configurationFiles>
                <!-- Specify any configuration files needed by the agent -->
                <file>${project.basedir}/path/to/your/agent-config.properties</file>
            </configurationFiles>
            <jvmArgs>
                <!-- Arguments to pass to the agent itself -->
                <jvmArg>-J--add-exports=jdk.internal.vm.compiler/jdk.vm.compiler.proxy=ALL-UNNAMED</jvmArg>
            </jvmArgs>
            <outputDirectory>${project.build.directory}/native-image</outputDirectory>
        </agent>
        <!-- Other native-image configurations if needed -->
    </configuration>
</plugin>

How It Should Work

When you configure the <agent/> block like this, the native-maven-plugin should:

Prepare the Agent: Ensure the agent JAR is available and correctly configured.
Intercept Executions: Identify Java executions that require agent instrumentation (this is the tricky part, as not all plugins are automatically intercepted).
Inject JVM Arguments: Automatically add the necessary -agentlib:native-image-agent=... arguments to the JVM command line for intercepted executions.

The Crucial Missing Link: The challenge often lies in how the native-maven-plugin communicates its agent configuration to other plugins, like exec-maven-plugin. The exec-maven-plugin runs in a forked JVM, and by default, it doesn't inherit JVM arguments or agent configurations from the parent Maven process or other plugins unless explicitly told to.

Linking `native-maven-plugin` and `exec-maven-plugin`

To make this work seamlessly, you usually need to ensure that the exec-maven-plugin is configured to receive the agent arguments. This can sometimes be achieved by:

Using Maven Profiles: Define separate Maven profiles where the native-maven-plugin is configured with the agent, and then have executions of exec-maven-plugin activate those profiles.
Explicitly Passing JVM Args: While you want to avoid manual configuration, sometimes you might need to reference properties set by the native-maven-plugin or directly pass the agent arguments.

Let's refine the exec-maven-plugin configuration to potentially pick up the agent configuration if the native-maven-plugin exposes it via properties. The native-maven-plugin might make the agent arguments available as Maven properties. You would need to check the plugin's specific property outputs.

If the native-maven-plugin configures the agent with an outputDirectory, it might set a property like ${native.agent.output.dir}. You could then use this:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>
    <version>3.0.0</version>
    <executions>
        <execution>
            <id>java-agent-exec</id>
            <goals>
                <goal>exec</goal>
            </goals>
            <phase>test</phase>
            <configuration>
                <executable>java</executable>
                <workingDirectory>${project.build.directory}</workingDirectory>
                <arguments>
                    <argument>-agentlib:native-image-agent=config-output-dir=${native.agent.output.dir}</argument> <!-- Assuming this property exists -->
                    <argument>-classpath</argument>
                    <classpath/>
                    <argument>${mainClass}</argument>
                </arguments>
            </configuration>
        </execution>
    </executions>
</plugin>

Important Note: This assumes the native-maven-plugin actually sets a property like ${native.agent.output.dir}. If it doesn't, or if it doesn't automatically inject the agent configuration into the exec plugin's environment, you might be back to needing to manually construct the jvmArgs. The best practice is to have the native-maven-plugin manage this entirely.

What's Next: Debugging and Clarification

Given your experience, you've likely already tried many things. The core issue seems to be the lack of automatic agent injection by the native-maven-plugin into the exec-maven-plugin's forked process. The documentation might be implying an integration that isn't fully realized or is dependent on specific configurations not clearly explained.

Recommendation:

Examine native-maven-plugin Documentation: Scour the official GraalVM Native Build Tools documentation for any sections specifically detailing how the agent configuration interacts with other Maven plugins, especially forked executions like exec-maven-plugin or maven-surefire-plugin.
Check Plugin Properties: Use mvn help:effective-pom or mvn -X output during a build that does involve the native-maven-plugin's agent configuration to see if any properties related to the agent are being set. You can then try referencing these properties in your exec-maven-plugin configuration.
Consider Profile Activation: Structure your pom.xml using profiles. Have a profile that enables the agent in native-maven-plugin and potentially includes configurations for exec-maven-plugin that activate when this profile is used.
File a Detailed Issue: If, after thorough investigation, you still can't find a clear path and suspect a potential gap in the plugin's functionality or documentation, filing a detailed issue on the GraalVM Native Build Tools GitHub repository is the best next step. Provide your pom.xml, the mvn -X output, and a clear description of the behavior you expect versus what you're observing. Your constructive feedback is invaluable!

It's frustrating when the tooling doesn't behave as intuitively expected, especially when you know the potential it holds. Keep pushing, and hopefully, we can get this resolved soon!