Skip to content

Latest commit

 

History

History
122 lines (92 loc) · 3.98 KB

DEVELOPING.md

File metadata and controls

122 lines (92 loc) · 3.98 KB

Documentation for Developers

This document describes how to set up and develop Native Build Tools on your local machine.

Environment

Start by setting JAVA_HOME to a Gradle-compatible JDK.

Some build tasks require a GraalVM JDK (e.g., tests). You should set GRAALVM_HOME to an appropriate GraalVM JDK.

IDE Setup

The Native Build Tools repository is structured as a Gradle multi-project, with the Maven and Gradle plugins declared as subprojects of the root project. To configure it in your IDE (e.g., IntelliJ IDEA), import the root project, and the IDE should automatically detect and include the subprojects.

Building and Testing

You can use the various commands in the Gradle build lifecycle to build and test the project. Some examples are (all executed from the root of the repository):

# Compile all projects
./gradlew assemble

# Run unit tests in all projects
./gradlew test

# Run functional tests in all projects
./gradlew funTest

# Compile only the native-gradle-plugin (for example)
./gradlew :native-gradle-plugin:assemble

# Build and run all tests, complete (and very long) build
./gradlew build

Debugging Plugin(s)

It is often useful to attach a debugger to the Gradle and Maven plugins during a project build.

For the Gradle plugin, this can be accomplished by passing debugger options to the Gradle daemon via org.gradle.jvmargs, for example:

JAVA_OPTS="-Dorg.gradle.jvmargs=-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=8000" ./gradlew assemble

The Gradle daemon will suspend on start-up, wait for you to attach a debugger, and then remain attached for subsequent Gradle commands.

For the Maven plugin, simply use the mvnDebug command in place of the mvn command.

Testing Local Changes with an Existing Project

A common development task is to modify a plugin and then test it with an existing project.

To do this, first modify the project as necessary, and then build and publish the plugins:

./gradlew publishAllPublicationsToCommonRepository --no-parallel

The above command publishes to a "common" repository located at build/common-repo.

Next, update the project build files:

  1. Update the version string. The version can be found manually by searching for the published artifacts in build/common-repo, or alternatively by checking the nativeBuildTools property here.
  2. Update the list of repositories to include and prioritize the common repo.

Gradle

Make the following changes to the build files:

# build.gradle
 plugins {
     ...
-    id 'org.graalvm.buildtools.native' version '0.9.25'
+    id 'org.graalvm.buildtools.native' version '0.10.5-SNAPSHOT'
 }

 repositories {
+    maven {
+        name = "common"
+        url = "$NATIVE_BUILD_TOOLS_ROOT/build/common-repo"
+    }
     ...
 }

# settings.gradle
 pluginManagement {
     repositories {
+        maven {
+            name = "common"
+            url = "$NATIVE_BUILD_TOOLS_ROOT/build/common-repo"
+        }
         # NB: If repositories were not specified before, declaring the common
         # repo will overwrite the default repository; you may also need to
         # declare that repository explicitly.
         mavenCentral()
         ...
     }
 }

Then, run the Gradle command as usual.

Maven

Make the following changes to pom.xml:

# pom.xml
 <project ...>
   <properties>
-    <native.maven.plugin.version>0.9.25</native.maven.plugin.version>
+    <native.maven.plugin.version>0.10.5-SNAPSHOT</native.maven.plugin.version>
   </properties>
   ...
+  <pluginRepositories>
+    <pluginRepository>
+      <id>common</id>
+      <url>file://$NATIVE_BUILD_TOOLS_ROOT/build/common-repo</url>
+    </pluginRepository>
+  </pluginRepositories>
 </project>

Then, run the Maven command with the -U flag to force Maven to use an updated snapshot (e.g., mvn -Pnative package -U).