Add developer documentation #678

DSouzaM · 2025-01-15T15:34:11Z

While debugging a NI agent issue I found myself needing to modify and debug the Gradle plugin. This change adds some developer documentation to explain setup and some common workflows (at least, the ones I needed).

Tracked internally as GR-61396.

I also tried to incorporate the suggestions in #656 w.r.t. environment setup.

oracle-contributor-agreement · 2025-01-15T15:34:19Z

Thank you for your pull request and welcome to our community! To contribute, please sign the Oracle Contributor Agreement (OCA).
The following contributors of this PR have not signed the OCA:

PR author: [email protected] (@DSouzaM)

To sign the OCA, please create an Oracle account and sign the OCA in Oracle's Contributor Agreement Application.

When signing the OCA, please provide your GitHub username. After signing the OCA and getting an OCA approval from Oracle, this PR will be automatically updated.

If you are an Oracle employee, please make sure that you are a member of the main Oracle GitHub organization, and your membership in this organization is public.

dnestoro · 2025-02-13T10:03:09Z

native-maven-plugin/README.md

-```shell
-./gradlew publishAllPublicationsToCommonRepository
+```bash
+./gradlew :native-maven-plugin:publishToMavenLocal --no-parallel


Have you tried this command if it works?

Yes it will work. Although personally I'd avoid polluting maven local and stick with the "common repository" (I usually add a local repository to Gradle/Maven builds to avoid the erratic behavior of maven local).

@melix could you explain how to use the common repository? After grepping this repo I still don't really understand how it works.

I tried ./gradlew publishAllPublicationsToCommonRepository --no-parallel but my changes were not picked up
(presumably I need to use it in my project's build definition).

There is nothing special here, publishAllPublicationsToCommonRepository will update the repository found in build/common-repo, and for sure you need to use it in your project definition. For example in Gradle you'd simply add a repository which points to build/common-repo, and in Maven you'd add a <repository>. You don't have to go that way, you can publish to Maven local, but I personally think it's a bad practice, because Maven local is polluted with dozens of libraries which may make us accidentally think that a build is working, when if you try it on a different machine, it would break.

dnestoro · 2025-02-13T10:03:21Z

native-gradle-plugin/README.md


 ```bash
-./gradlew publishToMavenLocal --no-parallel
+./gradlew :native-gradle-plugin:publishToMavenLocal --no-parallel


Have you tried this command if it works?

Yes, it works. It publishes only the gradle plugin and not the maven one.

dnestoro · 2025-02-13T10:06:00Z

DEVELOPING.md

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


Why do we need both this and SNAPSHOT?

I wrote this as a "diff" code sample to show how the existing build.gradle file might change (in this case, replacing a real release with a snapshot release)

dnestoro · 2025-02-13T10:06:24Z

DEVELOPING.md

+For Maven, simply bump the version and it should try the local repository automatically:
+```bash
+# pom.xml
+-        <native.maven.plugin.version>0.9.25</native.maven.plugin.version>


Same as above, why do we need this and SNAPSHOT?

DEVELOPING.md

dnestoro · 2025-02-13T10:09:50Z

DEVELOPING.md

+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


@melix can you please verify this section, because I didn't use these commands in the past?

dnestoro · 2025-02-13T10:11:40Z

Hey @DSouzaM, thanks for this PR. It will be really helpful. I just left some minor suggestions/questions, but in general, the PR looks good!

DEVELOPING.md

DSouzaM · 2025-03-03T20:21:42Z

Sorry about the delay on my end! I expected a GitHub notification when there were comments/updates on the PR, but I guess not.

DSouzaM · 2025-03-04T17:01:23Z

ok @melix, this is ready for review.

melix

Thanks for doing this, left a few minor changes

melix · 2025-03-04T17:12:14Z

DEVELOPING.md

+./gradlew :native-gradle-plugin:assemble
+
+# Build and run all tests
+./gradlew build


See you in 10 days :)

what's in 10 days? 😱

I mean if you run all tests, all functional tests, all verification in a single build, on a single machine, you can grab a few cups of coffee :)

😆 good call, we should be conscientious of the planet (and our users' time)

melix · 2025-03-04T17:13:39Z

DEVELOPING.md

+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).


Suggested change

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).

ah, good catch

melix · 2025-03-04T17:16:23Z

DEVELOPING.md

+# 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


Suggested change

# 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

# 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

olyagpl · 2025-03-05T08:38:48Z

native-maven-plugin/README.md

 ```

+A snapshot will be published to `build/common-repo`. For more details, see the [Developer documentation](../DEVELOPING.md).


will be published or is published after you run the build command above?

DEVELOPING.md

olyagpl · 2025-03-05T08:48:19Z

DEVELOPING.md

+./gradlew build
+```
+
+


Two lines empty space

DEVELOPING.md

dnestoro · 2025-03-05T09:41:51Z

@DSouzaM please resolve remaining comments, so we can merge this PR today

Co-authored-by: Olga Gupalo <[email protected]>

oracle-contributor-agreement bot added the OCA Required At least one contributor does not have an approved Oracle Contributor Agreement. label Jan 15, 2025

Add developer documentation

ed3948c

DSouzaM force-pushed the md/improve-docs branch from d8f1b14 to ed3948c Compare January 15, 2025 15:36

oracle-contributor-agreement bot added OCA Verified All contributors have signed the Oracle Contributor Agreement. and removed OCA Required At least one contributor does not have an approved Oracle Contributor Agreement. labels Jan 15, 2025

dnestoro reviewed Feb 13, 2025

View reviewed changes

dnestoro requested review from olyagpl and melix February 13, 2025 10:11

olyagpl previously approved these changes Feb 13, 2025

View reviewed changes

Polish developer documentation

6a250b4

DSouzaM dismissed olyagpl’s stale review via 6a250b4 March 3, 2025 20:37

Use common repo instead of local repo

fe4cc94

DSouzaM force-pushed the md/improve-docs branch from d7102c6 to fe4cc94 Compare March 4, 2025 17:14

melix requested changes Mar 4, 2025

View reviewed changes

melix previously approved these changes Mar 4, 2025

View reviewed changes

Better command examples; fix version string location

6e1272c

DSouzaM force-pushed the md/improve-docs branch from 2a476eb to 6e1272c Compare March 4, 2025 19:06

olyagpl previously approved these changes Mar 5, 2025

View reviewed changes

DSouzaM dismissed stale reviews from olyagpl and melix via c026664 March 5, 2025 14:12

DSouzaM force-pushed the md/improve-docs branch from c026664 to bfe0108 Compare March 5, 2025 14:16

olyagpl approved these changes Mar 5, 2025

View reviewed changes

Apply suggestions from code review

62bf70b

Co-authored-by: Olga Gupalo <[email protected]>

DSouzaM force-pushed the md/improve-docs branch from bfe0108 to 62bf70b Compare March 6, 2025 01:26

dnestoro merged commit d65f4a0 into graalvm:master Mar 6, 2025
137 checks passed

DSouzaM deleted the md/improve-docs branch March 6, 2025 14:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add developer documentation #678

Add developer documentation #678

DSouzaM commented Jan 15, 2025

oracle-contributor-agreement bot commented Jan 15, 2025

dnestoro Feb 13, 2025

melix Feb 13, 2025

DSouzaM Mar 3, 2025 •

edited

Loading

melix Mar 4, 2025

dnestoro Feb 13, 2025

DSouzaM Mar 3, 2025

dnestoro Feb 13, 2025

DSouzaM Mar 3, 2025

dnestoro Feb 13, 2025

dnestoro Feb 13, 2025

dnestoro commented Feb 13, 2025

DSouzaM commented Mar 3, 2025

DSouzaM commented Mar 4, 2025

melix left a comment

melix Mar 4, 2025

DSouzaM Mar 4, 2025

melix Mar 4, 2025

DSouzaM Mar 4, 2025

melix Mar 4, 2025

DSouzaM Mar 4, 2025

melix Mar 4, 2025

olyagpl Mar 5, 2025

olyagpl Mar 5, 2025

dnestoro commented Mar 5, 2025

	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).

		```

		A snapshot will be published to `build/common-repo`. For more details, see the [Developer documentation](../DEVELOPING.md).

Add developer documentation #678

Add developer documentation #678

Conversation

DSouzaM commented Jan 15, 2025

oracle-contributor-agreement bot commented Jan 15, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DSouzaM Mar 3, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dnestoro commented Feb 13, 2025

DSouzaM commented Mar 3, 2025

DSouzaM commented Mar 4, 2025

melix left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dnestoro commented Mar 5, 2025

DSouzaM Mar 3, 2025 •

edited

Loading