Skip to content

Commit 6e73d8a

Browse files
starksm64starksm64
authored
Merge pull request #1194 from stalep/gradle-doc
added gradle-tooling doc. splitted up the tooling into maven/gradle/cli
2 parents 0c56450 + 8e30d75 commit 6e73d8a

File tree

6 files changed

+604
-358
lines changed

6 files changed

+604
-358
lines changed

‎docs/src/main/asciidoc/cli-tooling.adoc‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
= Building {project-name} apps with {project-name} Command Line Interface (CLI)
2+
3+
== Installing the CLI
4+
5+
The {project-name} CLI is provided as a native binary for Linux and macOS or as a jar-file for
6+
all operating systems.
7+
8+
=== Native CLI
9+
10+
Download the binaries here:
11+
12+
* https://coming-soon[Linux Binary] (coming soon)
13+
* https://coming-soon[macOS Binary] (coming soon)
14+
15+
We recommend that you create a specific {project-name} folder, eg '~/quarkus' and move the
16+
binary there.
17+
Then in your shell profile (for Bash shell edit '~/.bash_profile'), export the 'QUARKUS_HOME'
18+
folder and add that to your 'PATH':
19+
20+
[source]
21+
export QUARKUS_HOME=/path/to/quarkus-cli
22+
export PATH="$PATH:$QUARKUS_HOME"
23+
24+
Reload your terminal or do:
25+
26+
[source]
27+
source ~/.bash_profile
28+
29+
Now you can run the {project-name} CLI:
30+
31+
[source]
32+
$ quarkus --help
33+
34+
This will display the help information with all the available commands.
35+
36+
[source]
37+
$ quarkus -i
38+
39+
This will start the {project-name} CLI in interactive mode.
40+
41+
=== Jar CLI
42+
43+
Download the jar-file here:
44+
* https://coming-soon[jar-file] (coming soon)
45+
46+
As with the native CLI we recommend that you copy the binary to a specific folder, eg '~/quarkus'.
47+
The jar file requires Java 8 or newer to run. To start the CLI:
48+
49+
[source]
50+
$ java -jar quarkus-cli.jar
51+
52+
The jar file CLI accepts all the same options and commands as the native binary.
53+
54+
Note: In the examples below switch out 'quarkus' with 'java -jar quarkus-cli.jar'.
55+
56+
57+
[[project-creation]]
58+
== Creating a new project
59+
60+
To create a new project we use the create-project command:
61+
62+
[source]
63+
$ quarkus create-project hello-world
64+
65+
This will create a folder called 'hello-world' in your current working directory using default
66+
groupId, artifactId and version values
67+
(groupId='com.acme', artifactId='quarkus' and version='1.0.0-SNAPSHOT').
68+
69+
To specify the groupId, artifactId and version values,
70+
use the '--groupid', '--artifactid' and '--version' options:
71+
72+
[source]
73+
$ quarkus create-project --groupid=com.foo --artifactId=bar --version=1.0 hello-world
74+
75+
76+
Use the help option to display all the possible options:
77+
78+
[source]
79+
$ quarkus create-project --help
80+
81+
== Dealing with extensions
82+
83+
The {project-name} CLI can obtain a list of the available extensions with:
84+
85+
[source]
86+
$ quarkus list-extensions
87+
88+
To more easily get an overview and only display the extension names:
89+
90+
[source]
91+
$ quarkus list-extensions -n
92+
93+
94+
== Adding extension(s)
95+
96+
The {project-name} CLI can add {project-name} extensions to your project with the 'add-extension'
97+
command:
98+
99+
[source]
100+
$ quarkus add-extension --extension=hibernate-validator /path/to/my/project
101+
102+
The argument path either needs to be the base folder for the project or a direct path to the
103+
build file.
104+
105+
== Development mode
106+
107+
To start dev mode from the {project-name} CLI do:
108+
109+
[source]
110+
$ quarkus dev /path/to/my/project
111+
112+
As with 'add-extension' the argument path needs to be the base folder for the project or a
113+
direct path to the build file.
114+
115+

‎docs/src/main/asciidoc/gradle-config.adoc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
= {project-name} - Gradle Plugin Repositories
2+
3+
// tag::repositories[]
4+
{project-name} Gradle plugin is not yet published to the https://plugins.gradle.org/[Gradle Plugin Portal],
5+
so you need to add the following to your '~/.gradle/init.gradle' file:
6+
[source, groovy, subs=attributes+]
7+
----
8+
allprojects {
9+
buildscript { <1>
10+
repositories {
11+
mavenCentral()
12+
}
13+
dependencies {
14+
classpath 'io.quarkus:quarkus-gradle-plugin:{quarkus-version}'
15+
}
16+
}
17+
repositories {
18+
mavenCentral()
19+
}
20+
}
21+
----
22+
23+
<1> The buildscript block is needed for the {project-name} Gradle plugin.
24+
25+
Alternatively you add the buildscript and repositories blocks in your `build.gradle` file.
26+
27+
// end::repositories[]

‎docs/src/main/asciidoc/gradle-tooling.adoc‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
= Building {project-name} apps with Gradle
2+
3+
== Gradle configuration
4+
5+
Configure Gradle as indicated in the link:gradle-config.html[Gradle configuration page].
6+
7+
At the moment there is no way of automatically generating a new project using the {project-name} Gradle plugin,
8+
luckily setting up a {project-name} project with Gradle is very simple. You only need to add the {project-name} Gradle plugin like this:
9+
10+
[source,groovy,subs=attributes+]
11+
----
12+
apply plugin: 'io.quarkus.gradle.plugin'
13+
----
14+
Note: If you did not follow the steps indicated in the link:gradle-config.html[Gradle configuration page]
15+
you need to add this block to your 'build.gradle' file as well:
16+
17+
[source,groovy,subs=attributes+]
18+
----
19+
buildscript {
20+
repositories {
21+
mavenCentral()
22+
}
23+
dependencies {
24+
classpath 'io.quarkus:quarkus-gradle-plugin:{quarkus-version}'
25+
}
26+
}
27+
----
28+
29+
[[project-creation]]
30+
== Creating a new project
31+
32+
For now we have to manually create a Gradle project file for {project-name}.
33+
Here is a complete sample file for a simple rest project:
34+
35+
[source,groovy,subs=attributes+]
36+
----
37+
apply plugin: 'java'
38+
apply plugin: 'maven'
39+
apply plugin: 'io.quarkus.gradle.plugin' <1>
40+
41+
42+
group = 'org.acme'
43+
version = '1.0-SNAPSHOT'
44+
45+
buildscript { <2>
46+
repositories {
47+
mavenCentral()
48+
}
49+
dependencies {
50+
classpath 'io.quarkus:quarkus-gradle-plugin:{quarkus-version}'
51+
}
52+
}
53+
54+
repositories { <3>
55+
mavenCentral()
56+
}
57+
58+
dependencies { <4>
59+
compileOnly group: 'io.quarkus', name: 'quarkus-resteasy-deployment', version:'{quarkus-version}'
60+
}
61+
----
62+
63+
<1> The {project-name} plugin needs to be applied.
64+
<2> The buildscript block can be omitted if you added it to your '~/.gradle/init.gradle' file.
65+
<3> The repositories block can be omitted if you added it to your '~/.gradle/init.gradle' file.
66+
<4> This dependency is needed for a rest application similar to the getting started example.
67+
68+
69+
== Dealing with extensions
70+
71+
From inside a {project-name} project, you can obtain a list of the available extensions with:
72+
73+
[source]
74+
gradle list-extensions
75+
76+
Functionality to automatically add extensions to your Gradle project is not implemented yet (coming soon).
77+
78+
== Development mode
79+
80+
{project-name} comes with a built-in development mode.
81+
Run you application with:
82+
83+
[source]
84+
gradle quarkus-dev
85+
86+
You can then update the application sources, resources and configurations.
87+
The changes are automatically reflected in your running application.
88+
This is great to do development spanning UI and database as you see changes reflected immediately.
89+
90+
`quarkus-dev` enables hot deployment with background compilation, which means that when you modify
91+
your Java files or your resource files and refresh your browser these changes will automatically take effect.
92+
This works too for resource files like the configuration property file.
93+
The act of refreshing the browser triggers a scan of the workspace, and if any changes are detected the
94+
Java files are compiled, and the application is redeployed, then your request is serviced by the
95+
redeployed application. If there are any issues with compilation or deployment an error page will let you know.
96+
97+
Hit `CTRL+C` to stop the application.
98+
99+
== Debugging
100+
101+
You can run a {project-name} application in debug mode using:
102+
103+
[source]
104+
gradle quarkus-dev --debug=true
105+
106+
Then, attach your debugger to `localhost:5005`.
107+
108+
== Import in your IDE
109+
110+
Once you have a <<project-creation, project generated>>, you can import it in your favorite IDE.
111+
The only requirement is the ability to import a Gradle project.
112+
113+
**Eclipse**
114+
115+
In Eclipse, click on: `File -> Import`.
116+
In the wizard, select: `Maven -> Existing Gradle Project`.
117+
On the next screen, select the root location of the project.
118+
The next screen list the found modules; select the generated project and click on `Finish`. Done!
119+
120+
In a separated terminal, run `gradle quarkus-dev`, and enjoy a highly productive environment.
121+
122+
**IntelliJ**
123+
124+
In IntelliJ:
125+
126+
1. From inside IntelliJ select `File -> New -> Project From Existing Sources...` or, if you are on the welcome dialog, select `Import project`.
127+
2. Select the project root
128+
3. Select `Import project from external model` and `Gradle`
129+
4. Next a few times (review the different options if needed)
130+
5. On the last screen click on Finish
131+
132+
In a separated terminal or in the embedded terminal, run `gradle quarkus-dev`. Enjoy!
133+
134+
**Apache Netbeans**
135+
136+
In Netbeans:
137+
138+
1. Select `File -> Open Project`
139+
2. Select the project root
140+
3. Click on `Open Project`
141+
142+
In a separated terminal or the embedded terminal, go to the project root and run `gradle quarkus-dev`. Enjoy!
143+
144+
**Visual Studio Code**
145+
146+
Open the project directory in VS Code. If you have installed the Java Extension Pack (grouping a set of Java extensions), the project is loaded as a Gradle project.
147+
148+
== Building a native image
149+
150+
Native images make {project-name} applications ideal for containers and serverless workloads.
151+
152+
Make sure to have `GRAALVM_HOME` configured and pointing to GraalVM version {graalvm-version}.
153+
154+
Create a native executable using: `gradle quarkus-native`.
155+
A native executable will be present in `build/`.
156+
157+
=== Build a container friendly executable
158+
159+
The native executable will be specific to your operating system.
160+
To create an executable that will run in a container, use the following:
161+
162+
[source, bash]
163+
----
164+
gradle quarkus-native --docker-build=true
165+
----
166+
167+
The produced executable will be a 64 bit Linux executable, so depending on your operating system
168+
it may no longer be runnable.
169+
However, it's not an issue as we are going to copy it to a Docker container.
170+

‎docs/src/main/asciidoc/maven-config.adoc‎

Lines changed: 0 additions & 57 deletions
This file was deleted.

0 commit comments

Comments
 (0)