From 6af2f68bc0687d2fdc046c6b5783cfe7f014fef7 Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Tue, 24 May 2022 18:32:15 -0500 Subject: [PATCH] Work on README for Gradle plugin projects --- devtools/gradle/README.adoc | 99 +++++++++++++++++++ devtools/gradle/README.md | 52 ---------- .../gradle-application-plugin/README.adoc | 10 ++ .../gradle-extension-plugin/README.adoc | 10 ++ 4 files changed, 119 insertions(+), 52 deletions(-) create mode 100644 devtools/gradle/README.adoc delete mode 100644 devtools/gradle/README.md create mode 100644 devtools/gradle/gradle-application-plugin/README.adoc create mode 100644 devtools/gradle/gradle-extension-plugin/README.adoc diff --git a/devtools/gradle/README.adoc b/devtools/gradle/README.adoc new file mode 100644 index 0000000000000..8ea5f258ccd6a --- /dev/null +++ b/devtools/gradle/README.adoc @@ -0,0 +1,99 @@ += Quarkus Gradle Support +:app-plugin-path: ./gradle-application-plugin +:extension-plugin-path: ./gradle-extension-plugin + +Gradle plugins for building xref:{app-plugin-path}/README.adoc[Quarkus applications] and +building xref:{extension-plugin-path}/README.adoc[Quarkus extensions]. + + +[[dev]] +== Develop + +Before starting development on these plugins, be sure to have <> the project. + +For IntelliJ users, see the notes for <> the project. + +Be sure to see the notes about <> your changes. + + +[[build]] +== Building + +Generally, after each pull or rebase the entire project should be built: + +[source] +---- +./mvnw -Dquickly +---- + +This builds the entire Quarkus codebase and publishes everything to mavenLocal. + +From there, this project works like any normal Gradle build. Run Gradle commands here +or any of the subprojects. + +However, see the important notes about <>. + + +[[testing]] +== Running Tests + +Each subproject defines its own set of tests which can just be run using normal Gradle operations. + +There are also integration tests located in `integration-tests/gradle`. + +[IMPORTANT] +==== +Before running integration tests, it is important that the entire Quarkus codebase be <> +and published into mavenLocal. +==== + +To run the integration tests, from the `integration-tests/gradle` directory: + +[source, bash] +---- +./mvnw test +---- + +A single integration test can be run by itself: + +[source, bash] +---- +./mvnw test -Dtest= +---- + +[NOTE] +==== +See <> for an alternative approach to integration testing. +==== + + +[[importing-intellij]] +== Importing using Intellij + +Disable "Maven Auto Import" for the Quarkus projects. Since the Gradle plugin has a pom.xml, +IntelliJ will configure this project as a Maven project. You need to configure it to be a Gradle +project. To do so, follow these instructions: + +. Go to File -> Project Structure +. In Modules, remove the `quarkus-gradle-plugin` and re-import as a Gradle project. + + +[[alt-testing]] +== Alternative Testing + +Another option for testing the plugin is to create a local project that uses the plugin and the features you are working on. + +Again, be sure the entire project is <>, then run the following: + +[source,bash] +---- + mvn io.quarkus:quarkus-maven-plugin:999-SNAPSHOT:create \ + -DprojectGroupId=${groupName} \ + -DprojectArtifactId=${name} \ + -DclassName="org.acme.quickstart.GreetingResource" \ + -DplatformArtifactId=quarkus-bom \ + -Dpath="/hello" \ + -DbuildTool=gradle +---- + +Follow the instructions in the https://quarkus.io/guides/gradle-tooling[Gradle Tooling Guide] for more information about the available commands. diff --git a/devtools/gradle/README.md b/devtools/gradle/README.md deleted file mode 100644 index 669bd9e9a6336..0000000000000 --- a/devtools/gradle/README.md +++ /dev/null @@ -1,52 +0,0 @@ -Quarkus Gradle Plugin -===================== - -Builds a Quarkus application, and provides helpers to launch dev-mode, the Quarkus CLI and the build of native images. - -Releases are published at https://plugins.gradle.org/plugin/io.quarkus . - -Integration Tests ----------------- - -Integration tests are located in `integration-tests/gradle`. Use the following command to run them: - -```bash -./gradlew test -``` - -Native test can be run using the command: - -```bash -./gradlew nativeTest -``` - -Local development ------------------ - -1. Build the entire Quarkus codebase by running `mvn clean install -DskipTests -DskipITs` in the project root - - This should install the Gradle plugin in your local maven repository. - -2. Create a sample project using the Maven plugin: - -```bash - mvn io.quarkus:quarkus-maven-plugin:999-SNAPSHOT:create \ - -DprojectGroupId=org.acme \ - -DprojectArtifactId=my-gradle-project \ - -DclassName="org.acme.quickstart.GreetingResource" \ - -DplatformArtifactId=quarkus-bom \ - -Dpath="/hello" \ - -DbuildTool=gradle -``` - -Follow the instructions in the [Gradle Tooling Guide](https://quarkus.io/guides/gradle-tooling) for more information about the available commands. - -Importing using Intellij -------------------------- - -Disable "Maven Auto Import" for the Quarkus projects. Since the Gradle plugin has a pom.xml, -IntelliJ will configure this project as a Maven project. You need to configure it to be a Gradle -project. To do so, follow these instructions: - - -1. Go to File -> Project Structure -2. In Modules, remove the `quarkus-gradle-plugin` and re-import as a Gradle project. diff --git a/devtools/gradle/gradle-application-plugin/README.adoc b/devtools/gradle/gradle-application-plugin/README.adoc new file mode 100644 index 0000000000000..391c666a216cb --- /dev/null +++ b/devtools/gradle/gradle-application-plugin/README.adoc @@ -0,0 +1,10 @@ += Quarkus Application Gradle Plugin +:root-project-path: .. + +Gradle plugin for developing Quarkus Applications + +Releases are published at https://plugins.gradle.org/plugin/io.quarkus. + +Topics related to developing this plugin are covered in xref:{root-project-path}/README.adoc. + +// todo : document usage of this plugin \ No newline at end of file diff --git a/devtools/gradle/gradle-extension-plugin/README.adoc b/devtools/gradle/gradle-extension-plugin/README.adoc new file mode 100644 index 0000000000000..c6a2a2768290b --- /dev/null +++ b/devtools/gradle/gradle-extension-plugin/README.adoc @@ -0,0 +1,10 @@ += Quarkus Extension Gradle Plugin +:root-project-path: .. + +Gradle plugin for developing Quarkus Extensions + +Releases are published at https://plugins.gradle.org/plugin/io.quarkus.extension. + +Most topics regarding developing this plugin are covered in xref:{root-project-path}/README.adoc. + +// todo : document usage of this plugin \ No newline at end of file