Improve the documentation relating to using the tracing agent to generate reflection config from the unit tests

[krisfoster]

I think the documentation for the maven tool needs to be expanded. It's not super clear what the process should be using the tracing agent when you have tests and when you build a native binary. Consider the following (assumes some project using maven that has tests, uses reflection etc and has a profile for the native build tools):

// Builds the tests natively and runs them - picks up the reflection config from target (-H:ConfigurationFileDirectories)
// Note that the native unit testing explicitly passes in the location of the tracing agent config, see above
mvn -Pnative -Dagent=true test

// Builds the native binary, BUT it doesn’t reference the reflection config. The binary fails at runtime
mvn -Pnative -Dagent=true package

What one needs to do is to copy over the reflection config generated by the tracing agent when running the tests. Without this, this leads to the binary failing at runtime.

Think we should have an example of working through this. Can fully understand that we don't necessarily want to copy over the tracing config, but the fact that the tests work with no change but the binary fails is confusing for the the end user.

Thanks!

[sbrannen]

@sdeleuze, is this similar to an issue you once raised?

[sdeleuze]

Yes I think. There is a pretty complete documentation on https://github.com/oracle/graalvm-reachability-metadata/blob/master/docs/CollectingMetadata.md but it is on reachability metadata side and it is currently Gradle only.

@gradinac Maybe we could document this properly on NBT Gradle and Maven documentation and just point reachability metadata to the related sections of NBT documentation.

[sdeleuze]

Potentially depends on #260.

[linghengqian]

• So, the documentation should provide a link to https://www.graalvm.org/dev/reference-manual/native-image/guides/use-native-image-maven-plugin/ ? But from a novice point of view, the pom.xml of https://github.com/graalvm/graalvm-demos/tree/master/fortune-demo is really quite complicated.

[linghengqian]

• Considering Add maven support for agent #343 , if the maven plugin has the same experience with the agent mode as the gradle plugin, shouldn't this issue be considered resolved? Because there is a metadataCopy task.

[sdeleuze]

Potentially yes.

@dnestoro Could you please check and close this issue if confirmed?