Add developer documentation #678
Conversation
|
Thank you for your pull request and welcome to our community! To contribute, please sign the Oracle Contributor Agreement (OCA).
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. |
oracle-contributor-agreement
bot
added
the
OCA Required
DSouzaM
force-pushed
the
md/improve-docs
branch
from
d8f1b14 to
ed3948c
Compare
oracle-contributor-agreement
bot
added
OCA Verified
| ```shell | ||
| ./gradlew publishAllPublicationsToCommonRepository | ||
| ```bash | ||
| ./gradlew :native-maven-plugin:publishToMavenLocal --no-parallel |
There was a problem hiding this comment.
Have you tried this command if it works?
There was a problem hiding this comment.
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).
|
|
||
| ```bash | ||
| ./gradlew publishToMavenLocal --no-parallel | ||
| ./gradlew :native-gradle-plugin:publishToMavenLocal --no-parallel |
There was a problem hiding this comment.
Have you tried this command if it works?
| # build.gradle | ||
| plugins { | ||
| ... | ||
| - id 'org.graalvm.buildtools.native' version '0.9.25' |
There was a problem hiding this comment.
Why do we need both this and SNAPSHOT?
| 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> |
There was a problem hiding this comment.
Same as above, why do we need this and SNAPSHOT?
| + <native.maven.plugin.version>0.10.5-SNAPSHOT</native.maven.plugin.version> | ||
| ``` | ||
|
|
||
| Then, run your build as usual. Gradle should find the plugin in the local repository and use it for the build. |
There was a problem hiding this comment.
I guess not only Gradle but Maven would find it as well. So maybe Gradle/Maven should find...
| 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 |
There was a problem hiding this comment.
@melix can you please verify this section, because I didn't use these commands in the past?
|
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! |
| @@ -0,0 +1,91 @@ | |||
| # Documentation for Developers | |||
|
|
|||
| This document describes how to set up and develop native-build-tools on your local machine. | |||
There was a problem hiding this comment.
native-build-tools -> Native Build Tools
|
|
||
| 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. |
There was a problem hiding this comment.
The native-build-tools repo ... -> The Native Build Tools repo
| 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 |
| ``` | ||
|
|
||
|
|
||
| ## Debugging plugin(s) |
|
|
||
| For the Maven plugin, simply use the `mvnDebug` command in place of the `mvn` command. | ||
|
|
||
| ## Testing local changes with an existing project |
There was a problem hiding this comment.
Testing Local Changes with an Existing Project| ``` | ||
|
|
||
| Then, run your build as usual. Gradle should find the plugin in the local repository and use it for the build. | ||
|
|
There was a problem hiding this comment.
Three empty lines at the end of the file
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.