From ed3948c7810168015f775fc001ba45d929ab91f0 Mon Sep 17 00:00:00 2001 From: Matt D'Souza Date: Wed, 15 Jan 2025 10:27:36 -0500 Subject: [PATCH 1/5] Add developer documentation --- DEVELOPING.md | 91 ++++++++++++++++++++++++++++++++++ README.md | 3 ++ native-gradle-plugin/README.md | 6 ++- native-maven-plugin/README.md | 8 +-- 4 files changed, 103 insertions(+), 5 deletions(-) create mode 100644 DEVELOPING.md diff --git a/DEVELOPING.md b/DEVELOPING.md new file mode 100644 index 000000000..27e837a59 --- /dev/null +++ b/DEVELOPING.md @@ -0,0 +1,91 @@ +# Documentation for Developers + +This document describes how to set up and develop native-build-tools on your local machine. + +## Environment + +The project uses Gradle as its build system. At the very minimum, you should set `JAVA_HOME` to a [Gradle-compatible JDK](https://docs.gradle.org/current/userguide/compatibility.html). + +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 repo is set up as a multi-project Gradle project, with the Maven and Gradle plugins declared as subprojects of the root project. +To set the project up in your IDE (e.g., IntelliJ IDEA), import the root project and the IDE should automatically import the subprojects. + +## Building & testing + +You can use the various commands in the [Gradle build lifecycle](https://docs.gradle.org/current/userguide/build_lifecycle.html) to build and test the project. +Some examples (all executed from the root of the repository): + +```bash +# Build all projects +./gradlew assemble + +# Build only the native-gradle-plugin (for example) +./gradlew :native-gradle-plugin:assemble + +# Build and run all tests +./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: + +```bash +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 to the local Maven repository: +```bash +./gradlew publishToMavenLocal --no-parallel +``` + +Next, update the plugin version string in the project build files. +The version can be found manually by searching for the published artifacts in `~/.m2/repository/org/graalvm/buildtools/native/`, or alternatively by checking the `nativeBuildTools` property [here](gradle/libs.versions.toml). + +For Gradle, the change looks like the following. +You may also need to direct Gradle to use the local Maven repository to resolve the plugin: +```bash +# build.gradle + plugins { + ... +- id 'org.graalvm.buildtools.native' version '0.9.25' ++ id 'org.graalvm.buildtools.native' version '0.10.5-SNAPSHOT' + } + + repositories { ++ mavenLocal() + ... + } + +# settings.gradle +pluginManagement { + repositories { ++ mavenLocal() + ... + } +} +``` + +For Maven, simply bump the version and it should try the local repository automatically: +```bash +# pom.xml +- 0.9.25 ++ 0.10.5-SNAPSHOT +``` + +Then, run your build as usual. Gradle should find the plugin in the local repository and use it for the build. + + + diff --git a/README.md b/README.md index faf97aee9..08f98d95e 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,9 @@ Repository which contains build tool plugins for interoperability with [GraalVM End-user documentation about the plugins can be found [here](https://graalvm.github.io/native-build-tools/). ## Contributing + +Documentation for common developer tasks can be found [here](DEVELOPING.md). + ### Projects * [native-maven-plugin](native-maven-plugin/README.md) * [native-gradle-plugin](native-gradle-plugin/README.md) diff --git a/native-gradle-plugin/README.md b/native-gradle-plugin/README.md index 38e9a3ff4..1c95454bd 100644 --- a/native-gradle-plugin/README.md +++ b/native-gradle-plugin/README.md @@ -6,12 +6,14 @@ End-user documentation about the plugins can be found [here](https://graalvm.git ## Building -This plugin can be built with this command: +This plugin can be built with this command (from the root directory): ```bash -./gradlew publishToMavenLocal --no-parallel +./gradlew :native-gradle-plugin:publishToMavenLocal --no-parallel ``` +For more details, see the [Developer documentation](../DEVELOPING.md). + In order to run testing part of this plugin you need to get (or build) corresponding `junit-platform-native` artifact. *You can also take a look at CI workflow [here](../.github/workflows/test-native-gradle-plugin.yml).* diff --git a/native-maven-plugin/README.md b/native-maven-plugin/README.md index ec32ec963..a6f980168 100644 --- a/native-maven-plugin/README.md +++ b/native-maven-plugin/README.md @@ -6,10 +6,12 @@ End-user documentation about the plugins can be found [here](https://graalvm.git ## Building -This plugin follows standard Maven plugin conventions and can be built with this command: +This plugin can be built with this command (from the root directory): -```shell -./gradlew publishAllPublicationsToCommonRepository +```bash +./gradlew :native-maven-plugin:publishToMavenLocal --no-parallel ``` +For more details, see the [Developer documentation](../DEVELOPING.md). + *You can also take a look at CI workflow [here](../.github/workflows/test-native-maven-plugin.yml).* From 6a250b479166412363b8301178110bad54e2c782 Mon Sep 17 00:00:00 2001 From: Matt D'Souza Date: Mon, 3 Mar 2025 15:36:42 -0500 Subject: [PATCH 2/5] Polish developer documentation --- DEVELOPING.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/DEVELOPING.md b/DEVELOPING.md index 27e837a59..6fa7e0cd8 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -1,6 +1,6 @@ # Documentation for Developers -This document describes how to set up and develop native-build-tools on your local machine. +This document describes how to set up and develop Native Build Tools on your local machine. ## Environment @@ -8,12 +8,12 @@ The project uses Gradle as its build system. At the very minimum, you should set Some build tasks require a GraalVM JDK (e.g., tests). You should set `GRAALVM_HOME` to an appropriate GraalVM JDK. -## IDE setup +## IDE Setup -The native-build-tools repo is set up as a multi-project Gradle project, with the Maven and Gradle plugins declared as subprojects of the root project. +The Native Build Tools repo is set up as a multi-project Gradle project, with the Maven and Gradle plugins declared as subprojects of the root project. To set the project up in your IDE (e.g., IntelliJ IDEA), import the root project and the IDE should automatically import the subprojects. -## Building & testing +## Building and Testing You can use the various commands in the [Gradle build lifecycle](https://docs.gradle.org/current/userguide/build_lifecycle.html) to build and test the project. Some examples (all executed from the root of the repository): @@ -30,7 +30,7 @@ Some examples (all executed from the root of the repository): ``` -## Debugging plugin(s) +## 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: @@ -43,7 +43,7 @@ The Gradle daemon will suspend on start-up, wait for you to attach a debugger, a For the Maven plugin, simply use the `mvnDebug` command in place of the `mvn` command. -## Testing local changes with an existing project +## 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 to the local Maven repository: @@ -85,7 +85,4 @@ For Maven, simply bump the version and it should try the local repository automa + 0.10.5-SNAPSHOT ``` -Then, run your build as usual. Gradle should find the plugin in the local repository and use it for the build. - - - +Then, run your build as usual. Gradle/Maven should find the plugin in the local repository and use it for the build. From fe4cc94aa98a0a864d631d62a92ac64383158896 Mon Sep 17 00:00:00 2001 From: Matt D'Souza Date: Tue, 4 Mar 2025 12:14:16 -0500 Subject: [PATCH 3/5] Use common repo instead of local repo --- DEVELOPING.md | 61 ++++++++++++++++++++++++---------- native-gradle-plugin/README.md | 4 +-- native-maven-plugin/README.md | 4 +-- 3 files changed, 47 insertions(+), 22 deletions(-) diff --git a/DEVELOPING.md b/DEVELOPING.md index 6fa7e0cd8..4dfebbb6b 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -46,16 +46,18 @@ For the Maven plugin, simply use the `mvnDebug` command in place of the `mvn` co ## 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 to the local Maven repository: +To do this, first modify the project as necessary, and then build and publish the plugins: ```bash -./gradlew publishToMavenLocal --no-parallel +./gradlew publishAllPublicationsToCommonRepository --no-parallel ``` +The above command publishes to a "common" repository located at `build/common-repo`. -Next, update the plugin version string in the project build files. -The version can be found manually by searching for the published artifacts in `~/.m2/repository/org/graalvm/buildtools/native/`, or alternatively by checking the `nativeBuildTools` property [here](gradle/libs.versions.toml). +Next, update the project build files: +1. Update the version string. The version can be found manually by searching for the published artifacts in `~/.m2/repository/org/graalvm/buildtools/native/`, or alternatively by checking the `nativeBuildTools` property [here](gradle/libs.versions.toml). +2. Update the list of repositories to include and prioritize the common repo. -For Gradle, the change looks like the following. -You may also need to direct Gradle to use the local Maven repository to resolve the plugin: +### Gradle +Make the following changes to the build files: ```bash # build.gradle plugins { @@ -64,25 +66,48 @@ You may also need to direct Gradle to use the local Maven repository to resolve + id 'org.graalvm.buildtools.native' version '0.10.5-SNAPSHOT' } - repositories { -+ mavenLocal() + repositories { ++ maven { ++ name = "common" ++ url = "$NATIVE_BUILD_TOOLS_ROOT/build/common-repo" ++ } ... } # settings.gradle -pluginManagement { - repositories { -+ mavenLocal() - ... - } -} + 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. -For Maven, simply bump the version and it should try the local repository automatically: +### Maven +Make the following changes to pom.xml: ```bash # pom.xml -- 0.9.25 -+ 0.10.5-SNAPSHOT + + +- 0.9.25 ++ 0.10.5-SNAPSHOT + + ... ++ ++ ++ common ++ file://$NATIVE_BUILD_TOOLS_ROOT/build/common-repo ++ ++ + ``` -Then, run your build as usual. Gradle/Maven should find the plugin in the local repository and use it for the build. +Then, run the Maven command with the `-U` flag to force Maven to use an updated snapshot (e.g., `mvn -Pnative package -U`). diff --git a/native-gradle-plugin/README.md b/native-gradle-plugin/README.md index 1c95454bd..73328d1e4 100644 --- a/native-gradle-plugin/README.md +++ b/native-gradle-plugin/README.md @@ -9,10 +9,10 @@ End-user documentation about the plugins can be found [here](https://graalvm.git This plugin can be built with this command (from the root directory): ```bash -./gradlew :native-gradle-plugin:publishToMavenLocal --no-parallel +./gradlew :native-gradle-plugin:publishAllPublicationsToCommonRepository --no-parallel ``` -For more details, see the [Developer documentation](../DEVELOPING.md). +A snapshot will be published to `build/common-repo`. For more details, see the [Developer documentation](../DEVELOPING.md). In order to run testing part of this plugin you need to get (or build) corresponding `junit-platform-native` artifact. diff --git a/native-maven-plugin/README.md b/native-maven-plugin/README.md index a6f980168..2a4f84303 100644 --- a/native-maven-plugin/README.md +++ b/native-maven-plugin/README.md @@ -9,9 +9,9 @@ End-user documentation about the plugins can be found [here](https://graalvm.git This plugin can be built with this command (from the root directory): ```bash -./gradlew :native-maven-plugin:publishToMavenLocal --no-parallel +./gradlew :native-maven-plugin:publishAllPublicationsToCommonRepository --no-parallel ``` -For more details, see the [Developer documentation](../DEVELOPING.md). +A snapshot will be published to `build/common-repo`. For more details, see the [Developer documentation](../DEVELOPING.md). *You can also take a look at CI workflow [here](../.github/workflows/test-native-maven-plugin.yml).* From 6e1272cbaacb4eb69a97cd52e013fa18a42b0664 Mon Sep 17 00:00:00 2001 From: Matt D'Souza Date: Tue, 4 Mar 2025 12:22:51 -0500 Subject: [PATCH 4/5] Better command examples; fix version string location --- DEVELOPING.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/DEVELOPING.md b/DEVELOPING.md index 4dfebbb6b..b6d8dad1e 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -19,13 +19,19 @@ You can use the various commands in the [Gradle build lifecycle](https://docs.gr Some examples (all executed from the root of the repository): ```bash -# Build all projects +# Compile all projects ./gradlew assemble -# Build only the native-gradle-plugin (for example) +# 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 +# Build and run all tests, complete (and very long) build ./gradlew build ``` @@ -53,7 +59,7 @@ To do this, first modify the project as necessary, and then build and publish th 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 `~/.m2/repository/org/graalvm/buildtools/native/`, or alternatively by checking the `nativeBuildTools` property [here](gradle/libs.versions.toml). +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](gradle/libs.versions.toml). 2. Update the list of repositories to include and prioritize the common repo. ### Gradle From 62bf70b48846f2aea78e44d40969eaa1a56fa603 Mon Sep 17 00:00:00 2001 From: Matt D'Souza Date: Wed, 5 Mar 2025 09:12:18 -0500 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Olga Gupalo --- DEVELOPING.md | 15 +++++++++------ native-gradle-plugin/README.md | 2 +- native-maven-plugin/README.md | 5 ++++- 3 files changed, 14 insertions(+), 8 deletions(-) diff --git a/DEVELOPING.md b/DEVELOPING.md index b6d8dad1e..8b46bd519 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -4,19 +4,19 @@ This document describes how to set up and develop Native Build Tools on your loc ## Environment -The project uses Gradle as its build system. At the very minimum, you should set `JAVA_HOME` to a [Gradle-compatible JDK](https://docs.gradle.org/current/userguide/compatibility.html). +Start by setting `JAVA_HOME` to a [Gradle-compatible JDK](https://docs.gradle.org/current/userguide/compatibility.html). 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 repo is set up as a multi-project Gradle project, with the Maven and Gradle plugins declared as subprojects of the root project. -To set the project up in your IDE (e.g., IntelliJ IDEA), import the root project and the IDE should automatically import the subprojects. +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](https://docs.gradle.org/current/userguide/build_lifecycle.html) to build and test the project. -Some examples (all executed from the root of the repository): +Some examples are (all executed from the root of the repository): ```bash # Compile all projects @@ -35,8 +35,8 @@ Some examples (all executed from the root of the repository): ./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: @@ -50,6 +50,7 @@ The Gradle daemon will suspend on start-up, wait for you to attach a debugger, a 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: @@ -63,6 +64,7 @@ Next, update the project build files: 2. Update the list of repositories to include and prioritize the common repo. ### Gradle + Make the following changes to the build files: ```bash # build.gradle @@ -98,7 +100,8 @@ Make the following changes to the build files: Then, run the Gradle command as usual. ### Maven -Make the following changes to pom.xml: + +Make the following changes to _pom.xml_: ```bash # pom.xml diff --git a/native-gradle-plugin/README.md b/native-gradle-plugin/README.md index 73328d1e4..5b6ad018d 100644 --- a/native-gradle-plugin/README.md +++ b/native-gradle-plugin/README.md @@ -12,7 +12,7 @@ This plugin can be built with this command (from the root directory): ./gradlew :native-gradle-plugin:publishAllPublicationsToCommonRepository --no-parallel ``` -A snapshot will be published to `build/common-repo`. For more details, see the [Developer documentation](../DEVELOPING.md). +The command will publish a snapshot to `build/common-repo`. For more details, see the [Developer documentation](../DEVELOPING.md). In order to run testing part of this plugin you need to get (or build) corresponding `junit-platform-native` artifact. diff --git a/native-maven-plugin/README.md b/native-maven-plugin/README.md index 2a4f84303..e07be3ddc 100644 --- a/native-maven-plugin/README.md +++ b/native-maven-plugin/README.md @@ -12,6 +12,9 @@ This plugin can be built with this command (from the root directory): ./gradlew :native-maven-plugin:publishAllPublicationsToCommonRepository --no-parallel ``` -A snapshot will be published to `build/common-repo`. For more details, see the [Developer documentation](../DEVELOPING.md). +The command will publish a snapshot to `build/common-repo`. +For more details, see the [Developer documentation](../DEVELOPING.md). + +In order to run testing part of this plugin you need to get (or build) corresponding `junit-platform-native` artifact. *You can also take a look at CI workflow [here](../.github/workflows/test-native-maven-plugin.yml).*