Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rename metadataRepository and document feature #225

Merged
merged 1 commit into from
Mar 21, 2022
Merged

Rename metadataRepository and document feature #225

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
79 changes: 79 additions & 0 deletions docs/src/docs/asciidoc/gradle-plugin.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -335,6 +335,85 @@ include::../snippets/gradle/groovy/build.gradle[tags=add-agent-options-individua
include::../snippets/gradle/kotlin/build.gradle.kts[tags=add-agent-options-individual]
----

[[metadata-support]]
== JVM Reachability Metadata support

Since release 0.9.11, the plugin adds experimental support for the https://github.com/graalvm/jvm-reachability-metadata/[JVM reachability metadata repository].
This repository provides GraalVM configuration for libraries which do not officially support GraalVM native.

=== Enabling the metadata repository

Support needs to be enabled explicitly:

.Enabling the metadata repository
[source, groovy, role="multi-language-sample"]
----
include::../snippets/gradle/groovy/build.gradle[tags=enable-metadata-repository]
----

[source, kotlin, role="multi-language-sample"]
----
include::../snippets/gradle/kotlin/build.gradle.kts[tags=enable-metadata-repository]
----

A metadata repository consists of configuration files for GraalVM.
The plugin will automatically download the configuration metadata from the official repository if you supply the version of the repository you want to use:

.Enabling the metadata repository
[source, groovy, role="multi-language-sample"]
----
include::../snippets/gradle/groovy/build.gradle[tags=specify-metadata-repository-version]
----

[source, kotlin, role="multi-language-sample"]
----
include::../snippets/gradle/kotlin/build.gradle.kts[tags=specify-metadata-repository-version]
----

Alternatively, it is possible to use a _local repository_, in which case you can specify the path to the repository:

.Using a local repository
[source, groovy, role="multi-language-sample"]
----
include::../snippets/gradle/groovy/build.gradle[tags=specify-metadata-repository-file]
----

[source, kotlin, role="multi-language-sample"]
----
include::../snippets/gradle/kotlin/build.gradle.kts[tags=specify-metadata-repository-file]
----

=== Configuring the metadata repository

Once activated, for each library included in the native image, the plugin will automatically search for GraalVM JVM reachability metadata in the repository.
In some cases, you may need to exclude a particular module from the search.
This can be done by adding it to the exclude list:

.Excluding a module from search
[source, groovy, role="multi-language-sample"]
----
include::../snippets/gradle/groovy/build.gradle[tags=exclude-module-from-metadata-repo]
----

[source, kotlin, role="multi-language-sample"]
----
include::../snippets/gradle/kotlin/build.gradle.kts[tags=exclude-module-from-metadata-repo]
----

Last, it is possible for you to override the _metadata version_ of a particular module.
This may be interesting if there's no specific metadata available for the particular version of the library that you use, but that you know that a version works:

.Specifying the metadata version to use for a particular library
[source, groovy, role="multi-language-sample"]
----
include::../snippets/gradle/groovy/build.gradle[tags=specify-metadata-version-for-library]
----

[source, kotlin, role="multi-language-sample"]
----
include::../snippets/gradle/kotlin/build.gradle.kts[tags=specify-metadata-version-for-library]
----

[[plugin-configurations]]
== Configurations defined by the plugin

Expand Down
3 changes: 3 additions & 0 deletions docs/src/docs/asciidoc/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,13 @@ If you are interested in contributing, please refer to our https://github.com/gr

* Fix long classpath issue under Windows when running native tests
* Inherit environment variables and system properties from the surefire plugin configuration when executing tests
* Fix invocation of `native-image` when classpath contains spaces

==== Gradle plugin

* Add support for environment variables in native test execution
* Fix invocation of `native-image` when classpath contains spaces
* Add experimental support for the JVM reachability metadata repository

=== Release 0.9.10

Expand Down
43 changes: 43 additions & 0 deletions docs/src/docs/snippets/gradle/groovy/build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,3 +149,46 @@ graalvmNative {
}
}
// end::add-agent-options-individual[]

// tag::enable-metadata-repository[]
graalvmNative {
metadataRepository {
enabled = true
}
}
// end::enable-metadata-repository[]

// tag::specify-metadata-repository-version[]
graalvmNative {
metadataRepository {
version = "1.0.0"
}
}
// end::specify-metadata-repository-version[]

// tag::specify-metadata-repository-file[]
graalvmNative {
metadataRepository {
uri(file("metadata-repository"))
}
}
// end::specify-metadata-repository-file[]

// tag::exclude-module-from-metadata-repo[]
graalvmNative {
metadataRepository {
// Exclude this library from automatic metadata
// repository search
excludes.add("com.company:some-library")
}
}
// end::exclude-module-from-metadata-repo[]

// tag::specify-metadata-version-for-library[]
graalvmNative {
metadataRepository {
// Force the version of the metadata for a particular library
moduleToConfigVersion.put("com.company:some-library", "3")
}
}
// end::specify-metadata-version-for-library[]
44 changes: 44 additions & 0 deletions docs/src/docs/snippets/gradle/kotlin/build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,3 +162,47 @@ graalvmNative {
}
}
// end::add-agent-options-individual[]

// tag::enable-metadata-repository[]
graalvmNative {
metadataRepository {
enabled.set(true)
}
}
// end::enable-metadata-repository[]

// tag::specify-metadata-repository-version[]
graalvmNative {
metadataRepository {
version.set("1.0.0")
}
}
// end::specify-metadata-repository-version[]


// tag::specify-metadata-repository-file[]
graalvmNative {
metadataRepository {
uri(file("metadata-repository"))
}
}
// end::specify-metadata-repository-file[]

// tag::exclude-module-from-metadata-repo[]
graalvmNative {
metadataRepository {
// Exclude this library from automatic metadata
// repository search
excludes.add("com.company:some-library")
}
}
// end::exclude-module-from-metadata-repo[]

// tag::specify-metadata-version-for-library[]
graalvmNative {
metadataRepository {
// Force the version of the metadata for a particular library
moduleToConfigVersion.put("com.company:some-library", "3")
}
}
// end::specify-metadata-version-for-library[]
4 changes: 2 additions & 2 deletions ...functionalTest/groovy/org/graalvm/buildtools/gradle/NativeConfigRepoFunctionalTest.groovy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ class NativeConfigRepoFunctionalTest extends AbstractFunctionalTest {

buildFile << """
graalvmNative {
jvmReachabilityMetadataRepository {
metadataRepository {
excludedModules.add("org.graalvm.internal:library-with-reflection")
}
}
Expand All @@ -121,7 +121,7 @@ graalvmNative {

buildFile << """
graalvmNative {
jvmReachabilityMetadataRepository {
metadataRepository {
moduleToConfigVersion.put("org.graalvm.internal:library-with-reflection", "2")
}
}
Expand Down
2 changes: 1 addition & 1 deletion native-gradle-plugin/src/main/java/org/graalvm/buildtools/gradle/NativeImagePlugin.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -406,7 +406,7 @@ private GraalVMExtension registerGraalVMExtension(Project project) {
}

private void configureNativeConfigurationRepo(ExtensionAware graalvmNative) {
JvmReachabilityMetadataRepositoryExtension configurationRepository = graalvmNative.getExtensions().create("jvmReachabilityMetadataRepository", JvmReachabilityMetadataRepositoryExtension.class);
JvmReachabilityMetadataRepositoryExtension configurationRepository = graalvmNative.getExtensions().create("metadataRepository", JvmReachabilityMetadataRepositoryExtension.class);
configurationRepository.getEnabled().convention(false);
configurationRepository.getUri().convention(configurationRepository.getVersion().map(v -> {
try {
Expand Down
2 changes: 1 addition & 1 deletion samples/native-config-integration/build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ tasks.withType(Test).configureEach {
}

graalvmNative {
jvmReachabilityMetadataRepository {
metadataRepository {
enabled = true
def extension = System.getProperty("extension", '')
def repo = file("config-directory${extension ? '.' + extension : ''}")
Expand Down