Enhance Project Documentation and Testing

DEVELOPING.md

@@ -13,26 +13,58 @@ Some build tasks require a GraalVM JDK (e.g., tests). You should set `GRAALVM_HO
 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.
 
+## Projects
+
+This repo contains the following projects:
+
+- `native-gradle-plugin` — Gradle plugin that provides support for building and testing GraalVM native images in Gradle builds (tasks, DSL, and functional tests).
+- `native-maven-plugin` — Maven plugin that provides support for building and testing GraalVM native images in Maven builds (mojos and functional tests).
+- `junit-platform-native` (in `common/`) — JUnit Platform native support used by plugins to run on native image.
+- `utils` (in `common/`) — Shared utility code used across the plugins, tests, and internal build logic.
+- `graalvm-reachability-metadata` (in `common/`) — Common code related to the [GraalVM reachability metadata](https://github.com/oracle/graalvm-reachability-metadata) repository integration.
+- `docs` — Documentation sources and build for the user guide and changelog. Please keep up to date.
+
+Internal build logic (used to build this repository itself):
+
+- `settings-plugins` (in `build-logic`) — Gradle settings plugins and supporting tooling.
+- `aggregator` (in `build-logic`) — Composite build that aggregates internal build plugins and conventions.
+
 ## 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 are (all executed from the root of the repository):
+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 (and all the subprojects).
+Examples used in daily development follow (all executed from the root of the repository):
 
 ```bash
 # Compile all projects
 ./gradlew assemble
 
+# Compile only the native-gradle-plugin (for example)
+./gradlew :native-gradle-plugin:assemble
+
 # Run unit tests in all projects
 ./gradlew test
 
-# Run functional tests in all projects
-./gradlew funTest
+# Run functional tests in individual projects
+./gradlew :native-maven-plugin:functionalTest
+./gradlew :native-gradle-plugin:functionalTest
 
-# Compile only the native-gradle-plugin (for example)
-./gradlew :native-gradle-plugin:assemble
+# Run a specific test class
+ ./gradlew -DnoTestIsolation=true :native-maven-plugin:functionalTest --tests "org.graalvm.buildtools.maven.IntegrationTest"
+
+ # Run a specific test method (with spaces in their name)
+ ./gradlew -DnoTestIsolation=true :native-maven-plugin:functionalTest --tests "org.graalvm.buildtools.maven.IntegrationTest.run integration tests with failsafe plugin and agent"
+
+# Checkstyle
+./gradlew :graalvm-reachability-metadata:checkstyleMain :graalvm-reachability-metadata:checkstyleTest
+./gradlew :junit-platform-native:checkstyleMain :junit-platform-native:checkstyleTest
+./gradlew :native-gradle-plugin:inspections
+./gradlew :native-maven-plugin:inspections
 
 # Build and run all tests, complete (and very long) build
 ./gradlew build
+
+# Clean all projects
+./gradlew clean
 ```
 
 ## Debugging Plugin(s)
@@ -63,7 +95,7 @@ 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](gradle/libs.versions.toml).
 2. Update the list of repositories to include and prioritize the common repo.
 
-### Gradle
+### Testing with Gradle
 
 Make the following changes to the build files:
 ```bash
@@ -99,7 +131,7 @@ Make the following changes to the build files:
 ```
 Then, run the Gradle command as usual.
 
-### Maven
+### Testing with Maven
 
 Make the following changes to _pom.xml_:
 ```bash
@@ -120,3 +152,7 @@ Make the following changes to _pom.xml_:
 ```
 
 Then, run the Maven command with the `-U` flag to force Maven to use an updated snapshot (e.g., `mvn -Pnative package -U`).
+
+## Changelog
+
+Changelog must be updated for all significant changes. The changelog uses asciidoc and it is located in [docs](docs/src/docs/asciidoc/changelog.adoc).

README.md

@@ -27,6 +27,7 @@ Documentation for common developer tasks can be found [here](DEVELOPING.md).
 Examples can be found in the [samples subdirectory](samples).
 
 ### Contributing Code
-We welcome your code contributions. To get started, you will need to sign the [Oracle Contributor Agreement](https://oca.opensource.oracle.com) (OCA).
 
-Only pull requests from committers that can be verified as having signed the OCA can be accepted.
+We welcome your code contributions. To get started, you will need to sign the [Oracle Contributor Agreement](https://oca.opensource.oracle.com) (OCA). Only pull requests from committers that can be verified as having signed the OCA can be accepted.
+
+To see how to develop Native Build Tools go to [development guide](DEVELOPING.md).

build-logic/common-plugins/src/main/groovy/org.graalvm.build.github-actions-helper.gradle

@@ -2,7 +2,7 @@ import groovy.json.JsonOutput
 
 def matrixDefault = [
         "java-version": [ "17" ],
-        "os": [ "ubuntu-22.04", "windows-latest" ]
+        "os": [ "ubuntu-22.04", "windows-latest", "macos-latest" ]
 ]
 
 // # Following versions are disabled temporarily in order to speed up PR testing  "7.3.3", "7.2", "7.1", "6.8.3",

native-maven-plugin/src/functionalTest/groovy/org/graalvm/buildtools/maven/IntegrationTest.groovy

@@ -5,7 +5,7 @@ class IntegrationTest extends AbstractGraalVMMavenFunctionalTest {
         withSample("integration-test")
 
         when:
-        mvn '-Pnative', 'verify'
+        mvn '-Pnative', '-PquickBuild', 'verify'
 
         then:
         buildSucceeded

native-maven-plugin/src/testFixtures/groovy/org/graalvm/buildtools/maven/AbstractGraalVMMavenFunctionalTest.groovy

@@ -157,10 +157,16 @@ abstract class AbstractGraalVMMavenFunctionalTest extends Specification {
         var resultingSystemProperties = [
                 "common.repo.uri": System.getProperty("common.repo.uri"),
                 "seed.repo.uri": System.getProperty("seed.repo.uri"),
-                "maven.repo.local": testDirectory.resolve("local-repo").toFile().absolutePath
         ]
-        println "Using local repo: ${resultingSystemProperties['maven.repo.local']}"
+        if (System.getProperty("noTestIsolation") == null) {
+            resultingSystemProperties.put("maven.repo.local", testDirectory.resolve("local-repo").toFile().absolutePath)
+        }
         resultingSystemProperties.putAll(systemProperties)
+        if (resultingSystemProperties.containsKey("maven.repo.local")) {
+            println "Using local repo: ${resultingSystemProperties['maven.repo.local']}"
+        } else {
+            println "Using default Maven local repo"
+        }
 
         result = executor.execute(
                 testDirectory.toFile(),
@@ -170,7 +176,6 @@ abstract class AbstractGraalVMMavenFunctionalTest extends Specification {
                 new File(System.getProperty("maven.settings"))
         )
         println "Exit code is ${result.exitCode}"
-
     }
 
     void mvnDebug(String... args) {