Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve the Gradle tooling documentation #1403

Merged
merged 3 commits into from
Mar 12, 2019
Merged

Improve the Gradle tooling documentation #1403

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3a61991
Improve the Gradle tooling documentation
jnizet Mar 11, 2019
8dcd385
polish after gsmet's review
jnizet Mar 12, 2019
861cc3e
Some additional adjusments
gsmet Mar 12, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 28 additions & 12 deletions docs/src/main/asciidoc/gradle-config.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,26 +3,42 @@ include::./attributes.adoc[]

// tag::repositories[]
{project-name} Gradle plugin is not yet published to the https://plugins.gradle.org/[Gradle Plugin Portal],
so you need to add the following to your '~/.gradle/init.gradle' file:
so you need to add the following at the top of your './settings.gradle' file:
[source, groovy, subs=attributes+]
----
allprojects {
buildscript { <1>
pluginManagement {
repositories {
mavenCentral()
mavenCentral()
gradlePluginPortal()
}
dependencies {
classpath 'io.quarkus:quarkus-gradle-plugin:{quarkus-version}'
resolutionStrategy {
eachPlugin {
if (requested.id.id == 'io.quarkus.gradle.plugin') {
useModule("io.quarkus:quarkus-gradle-plugin:${requested.version}")
}
}
}
}
repositories {
mavenCentral()
}
}
----

<1> The buildscript block is needed for the {project-name} Gradle plugin.
Or, if you use the Gradle Kotlin DSL, you need to add the following at the top of your './settings.gradle.kts' file:
[source, kotlin, subs=attributes+]
----
pluginManagement {
repositories {
mavenCentral()
gradlePluginPortal()
}
resolutionStrategy {
eachPlugin {
if (requested.id.id == "io.quarkus.gradle.plugin") {
useModule("io.quarkus:quarkus-gradle-plugin:${requested.version}")
}
}
}
}
----

Alternatively you add the buildscript and repositories blocks in your `build.gradle` file.
This won't be necessary anymore once the Quarkus Gradle plugin is published in the Gradle plugin portal.

// end::repositories[]
118 changes: 64 additions & 54 deletions docs/src/main/asciidoc/gradle-tooling.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,82 +3,88 @@ include::./attributes.adoc[]

== Gradle configuration

Configure Gradle as indicated in the link:gradle-config.html[Gradle configuration page].
Configure your project as indicated in the link:gradle-config.html[Gradle configuration page].

At the moment there is no way of automatically generating a new project using the {project-name} Gradle plugin,
At the moment there is no way of automatically generating a new project using the {project-name} Gradle plugin,
luckily setting up a {project-name} project with Gradle is very simple. You only need to add the {project-name} Gradle plugin like this:

[source,groovy,subs=attributes+]
----
apply plugin: 'io.quarkus.gradle.plugin'
plugins {
id 'java'
id 'io.quarkus.gradle.plugin' version '{quarkus-version}'
}
----
Note: If you did not follow the steps indicated in the link:gradle-config.html[Gradle configuration page]
you need to add this block to your 'build.gradle' file as well:

[source,groovy,subs=attributes+]
or, if you use the Gradle Kotlin DSL:

[source,kotlin,subs=attributes+]
----
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'io.quarkus:quarkus-gradle-plugin:{quarkus-version}'
}
plugins {
java
id("io.quarkus.gradle.plugin") version "{quarkus-version}"
}
----

[[project-creation]]
== Creating a new project

For now we have to manually create a Gradle project file for {project-name}.
Here is a complete sample file for a simple rest project:
For now we have to manually create a Gradle project file for {project-name}.
Here is a complete sample file for a simple REST project:

[source,groovy,subs=attributes+]
----
apply plugin: 'java'
apply plugin: 'io.quarkus.gradle.plugin' <1>


buildscript { <2>
plugins {
id 'java'
id 'io.quarkus.gradle.plugin' version '{quarkus-version}' <1>
}

repositories {
repositories {
mavenCentral()

// this is temporary, all dependencies should be in central soon
maven {
//this is temporary, all dependencies should be in central soon
url 'http://repository.jboss.org/nexus/content/groups/public'
url = 'http://repository.jboss.org/nexus/content/groups/public'
}
}
dependencies {
classpath 'io.quarkus:quarkus-gradle-plugin:{quarkus-version}'
}
}

repositories { <3>
mavenCentral()
maven {
url 'http://repository.jboss.org/nexus/content/groups/public'
}
}

dependencies { <4>
compileOnly group: 'io.quarkus', name: 'quarkus-resteasy', version:'{quarkus-version}'
testOnly group: 'io.quarkus', name: 'quarkus-junit5', version:'{quarkus-version}'
testCompile group: 'io.rest-assured', name: 'rest-assured', version: '3.3.0'
dependencies { <2>
compileOnly 'io.quarkus:quarkus-resteasy:{quarkus-version}'
}
----

<1> The {project-name} plugin needs to be applied.
<2> The buildscript block can be omitted if you added it to your '~/.gradle/init.gradle' file.
<3> The repositories block can be omitted if you added it to your '~/.gradle/init.gradle' file.
<4> This dependency is needed for a rest application similar to the getting started example.
<2> This dependency is needed for a REST application similar to the getting started example.

Here's the same build script, using the Gradle Kotlin DSL:

[source,kotlin,subs=attributes+]
----
plugins {
java
id("io.quarkus.gradle.plugin") version "{quarkus-version}"
}

repositories {
mavenCentral()

// this is temporary, all dependencies should be in central soon
maven(url = uri("http://repository.jboss.org/nexus/content/groups/public"))
}

dependencies {
compileOnly("io.quarkus:quarkus-resteasy:{quarkus-version}")
}
----

== Dealing with extensions

From inside a {project-name} project, you can obtain a list of the available extensions with:

[source,shell]
gradle list-extensions
----
./gradlew list-extensions
----

Functionality to automatically add extensions to your Gradle project is not implemented yet (coming soon).

Expand All @@ -88,17 +94,19 @@ Functionality to automatically add extensions to your Gradle project is not impl
Run your application with:

[source,shell]
gradle quarkus-dev
----
./gradlew quarkus-dev
----

You can then update the application sources, resources and configurations.
The changes are automatically reflected in your running application.
This is great to do development spanning UI and database as you see changes reflected immediately.

`quarkus-dev` enables hot deployment with background compilation, which means that when you modify
`quarkus-dev` enables hot deployment with background compilation, which means that when you modify
your Java files or your resource files and refresh your browser these changes will automatically take effect.
This works too for resource files like the configuration property file.
The act of refreshing the browser triggers a scan of the workspace, and if any changes are detected the
Java files are compiled, and the application is redeployed, then your request is serviced by the
The act of refreshing the browser triggers a scan of the workspace, and if any changes are detected the
Java files are compiled, and the application is redeployed, then your request is serviced by the
redeployed application. If there are any issues with compilation or deployment an error page will let you know.

Hit `CTRL+C` to stop the application.
Expand All @@ -108,7 +116,9 @@ Hit `CTRL+C` to stop the application.
You can run a {project-name} application in debug mode using:

[source,shell]
gradle quarkus-dev --debug=true
----
./gradlew quarkus-dev --debug=true
----

Then, attach your debugger to `localhost:5005`.

Expand All @@ -120,11 +130,11 @@ The only requirement is the ability to import a Gradle project.
**Eclipse**

In Eclipse, click on: `File -> Import`.
In the wizard, select: `Maven -> Existing Gradle Project`.
In the wizard, select: `Gradle -> Existing Gradle Project`.
On the next screen, select the root location of the project.
The next screen list the found modules; select the generated project and click on `Finish`. Done!

In a separated terminal, run `gradle quarkus-dev`, and enjoy a highly productive environment.
In a separated terminal, run `./gradlew quarkus-dev`, and enjoy a highly productive environment.

**IntelliJ**

Expand All @@ -136,7 +146,7 @@ In IntelliJ:
4. Next a few times (review the different options if needed)
5. On the last screen click on Finish

In a separated terminal or in the embedded terminal, run `gradle quarkus-dev`. Enjoy!
In a separated terminal or in the embedded terminal, run `./gradlew quarkus-dev`. Enjoy!

**Apache Netbeans**

Expand All @@ -146,7 +156,7 @@ In Netbeans:
2. Select the project root
3. Click on `Open Project`

In a separated terminal or the embedded terminal, go to the project root and run `gradle quarkus-dev`. Enjoy!
In a separated terminal or the embedded terminal, go to the project root and run `./gradlew quarkus-dev`. Enjoy!

**Visual Studio Code**

Expand All @@ -158,7 +168,7 @@ Native executables make {project-name} applications ideal for containers and ser

Make sure to have `GRAALVM_HOME` configured and pointing to GraalVM version {graalvm-version}.

Create a native executable using: `gradle quarkus-native`.
Create a native executable using: `./gradlew quarkus-native`.
A native executable will be present in `build/`.

=== Build a container friendly executable
Expand All @@ -168,10 +178,10 @@ To create an executable that will run in a container, use the following:

[source,shell]
----
gradle quarkus-native --docker-build=true
./gradlew quarkus-native --docker-build=true
----

The produced executable will be a 64 bit Linux executable, so depending on your operating system
The produced executable will be a 64 bit Linux executable, so depending on your operating system
it may no longer be runnable.
However, it's not an issue as we are going to copy it to a Docker container.