Add developer documentation

DEVELOPING.md

@@ -0,0 +1,122 @@
+# 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](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 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 are (all executed from the root of the repository):
+
+```bash
+# 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:
+
+```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:
+```bash
+./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](gradle/libs.versions.toml).
+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
+ 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_:
+```bash
+# 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`).

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)

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:publishAllPublicationsToCommonRepository --no-parallel
 ```
 
+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-gradle-plugin.yml).*

native-maven-plugin/README.md

@@ -6,10 +6,15 @@ 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:publishAllPublicationsToCommonRepository --no-parallel
 ```
 
+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).*