anchor.diff:  include::./attributes.adoc[]
   = Building {project-name} apps with Maven
  +
  +[[project-creation]]
  +== Creating a new project
  +
  +With Maven, you can scaffold a new project with:
  +
  +[source,shell,subs=attributes+]
  +----
  +mvn io.quarkus:quarkus-maven-plugin:{quarkus-version}:create \
  +    -DprojectGroupId=my-groupId \
  +    -DprojectArtifactId=my-artifactId \
  +    -DprojectVersion=my-version \
  +    -DclassName="org.my.group.MyResource"
  +----
  +
  +NOTE: If you just launch `mvn io.quarkus:quarkus-maven-plugin:{quarkus-version}:create` the Maven plugin asks
  +for user inputs. You can disable (and use default values) this interactive mode by passing `-B` to the Maven command.
  +
  +The following table lists the attributes you can pass to the `create` command:
  +
  +[cols=3*,options="header"]
  +|===
  +| Attribute
  +| Default Value
  +| Description
  +
  +| `projectGroupId`
  +| `org.acme.sample`
  +| The group id of the created project
  +
  +| `projectArtifactId`
  +| _mandatory_
  +| The artifact id of the created project. Not passing it triggers the interactive mode.
  +
  +| `projectVersion`
  +| `1.0-SNAPSHOT`
  +| The version of the created project
  +
  +| `className`
  +| _Not created if omitted_
  +| The fully qualified name of the generated resource
  +
  +| `path`
  +| `/hello`
  +| The resource path, only relevant if `className` is set.
  +
  +| `extensions`
  +| _[]_
  +| The list of extensions to add to the project (comma-separated)
  +
  +|===
  +
  +If you decide to generate a REST resource (using the `className` attribute), the endpoint is exposed at: `http://localhost:8080/$path`.
  +If you use the default `path`, the URL is: http://localhost:8080/hello.
  +
  +The project is either generated in the current directory or in a directory named after the passed artifactId.
  +If the current directory is empty, the project is generated in-place.
  +
  +A `Dockerfile` is also generated in `src/main/docker`.
  +Instructions to build the image and run the container are written in the `Dockerfile`.
  +
  +== Dealing with extensions
  +
  +From inside a {project-name} project, you can obtain a list of the available extensions with:
  +
  +[source,shell]
  +mvn quarkus:list-extensions
  +
  +You can enable an extension using:
  +
  +[source,shell]
  +mvn quarkus:add-extension -Dextensions="hibernate-validator"
  +
  +Extensions are passed using a comma-separated list.
  +
  +== Development mode
  +
  +{project-name} comes with a built-in development mode.
  +Run you application with:
  +
  +[source,shell]
  +mvn compile 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 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 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.
  +
  +== Debugging
  +
  +You can run a {project-name} application in debug mode using:
  +
  +[source,shell]
  +mvn compile quarkus:dev -Ddebug=true
  +
  +Then, attach your debugger to `localhost:5005`.
  +
  +== Import in your IDE
  +
  +Once you have a <<project-creation, project generated>>, you can import it in your favorite IDE.
  +The only requirement is the ability to import a Maven project.
  +
  +**Eclipse**
  +
  +In Eclipse, click on: `File -> Import`.
  +In the wizard, select: `Maven -> Existing Maven 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 `mvn compile quarkus:dev`, and enjoy a highly productive environment.
  +
  +**IntelliJ**
  +
  +In IntelliJ:
  +
  +1. From inside IntelliJ select `File -> New -> Project From Existing Sources...` or, if you are on the welcome dialog, select `Import project`.
  +2. Select the project root
  +3. Select `Import project from external model` and `Maven`
  +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 `mvn compile quarkus:dev`. Enjoy!
  +
  +**Apache Netbeans**
  +
  +In Netbeans:
  +
  +1. Select `File -> Open Project`
  +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 `mvn compile quarkus:dev`. Enjoy!
  +
  +**Visual Studio Code**
  +
  +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 Maven project.
  +
  +== Building a native image
  +
  +Native images make {project-name} applications ideal for containers and serverless workloads.
  +
  +Make sure to have `GRAALVM_HOME` configured and pointing to GraalVM version {graalvm-version}.
  +Verify that your `pom.xml` has the proper `native` profile (see <<build-tool-maven>>).
  +
  +Create a native executable using: `mvn package -Pnative`.
  +A native executable will be present in `target/`.
  +
  +To run Integration Tests on the native executable, make sure to have the proper Maven plugin configured (see <<build-tool-maven>>) and launch the `verify` goal.
  +
  +[source,shell]
  +----
  +mvn package verify -Pnative
  +...
  +[quarkus-quickstart-runner:50955]     universe:     391.96 ms
  +[quarkus-quickstart-runner:50955]      (parse):     904.37 ms
  +[quarkus-quickstart-runner:50955]     (inline):   1,143.32 ms
  +[quarkus-quickstart-runner:50955]    (compile):   6,228.44 ms
  +[quarkus-quickstart-runner:50955]      compile:   9,130.58 ms
  +[quarkus-quickstart-runner:50955]        image:   2,101.42 ms
  +[quarkus-quickstart-runner:50955]        write:     803.18 ms
  +[quarkus-quickstart-runner:50955]      [total]:  33,520.15 ms
  +[INFO]
  +[INFO] --- maven-failsafe-plugin:2.22.0:integration-test (default) @ quarkus-quickstart-native ---
  +[INFO]
  +[INFO] -------------------------------------------------------
  +[INFO]  T E S T S
  +[INFO] -------------------------------------------------------
  +[INFO] Running org.acme.quickstart.GreetingResourceIT
  +Executing [/Users/starksm/Dev/JBoss/Protean/starksm64-quarkus-quickstarts/getting-started-native/target/quarkus-quickstart-runner, -Dquarkus.http.port=8081, -Dtest.url=http://localhost:8081, -Dquarkus.log.file.path=target/quarkus.log]
  +2019-02-28 16:52:42,020 INFO  [io.quarkus] (main) Quarkus started in 0.007s. Listening on: http://localhost:8080
  +2019-02-28 16:52:42,021 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy]
  +[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.081 s - in org.acme.quickstart.GreetingResourceIT
  +[INFO]
  +[INFO] Results:
  +[INFO]
  +[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
  +
  +...
  +----
  +
  +=== Build a container friendly executable
  +
  +The native executable will be specific to your operating system.
  +To create an executable that will run in a container, use the following:
  +
  +[source,shell]
  +----
  +mvn package -Pnative -Dnative-image.docker-build=true
  +----
  +
  +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.
  +
  +You can follow the link:building-native-image-guide.html[Build a native image guide] as well as link:kubernetes-guide.html[Deploying Application to Kubernetes and OpenShift] for more information.
   
   [[build-tool-maven]]
   == Maven configuration
  
positive.code: <2> Use the {project-name} Maven plugin that will hook into the build process
  <3> Use a native profile and plugin to activate GraalVM compilation
  <4> If you want to test your native image with Integration Tests, add the following plugin configuration. Test names `*IT` and annotated `@SubstrateTest` will be run against the native image. See the link:building-native-image-guide.html[Native image guide] for more info.
  
  [[project-creation]]
  == Creating a new project
  
  With Maven, you can scaffold a new project with:
  
  [source,shell,subs=attributes+]
  ----
  mvn io.quarkus:quarkus-maven-plugin:{quarkus-version}:create \
      -DprojectGroupId=my-groupId \
      -DprojectArtifactId=my-artifactId \
      -DprojectVersion=my-version \
      -DclassName="org.my.group.MyResource"
  ----
  
  NOTE: If you just launch `mvn io.quarkus:quarkus-maven-plugin:{quarkus-version}:create` the Maven plugin asks
  for user inputs. You can disable (and use default values) this interactive mode by passing `-B` to the Maven command.
  
  The following table lists the attributes you can pass to the `create` command:
  
  [cols=3*,options="header"]
  |===
  | Attribute
  | Default Value
  | Description
  
  | `projectGroupId`
  | `org.acme.sample`
  | The group id of the created project
  
  | `projectArtifactId`
  | _mandatory_
  | The artifact id of the created project. Not passing it triggers the interactive mode.
  
  | `projectVersion`
  | `1.0-SNAPSHOT`
  | The version of the created project
  
  | `className`
  | _Not created if omitted_
  | The fully qualified name of the generated resource
  
  | `path`
  | `/hello`
  | The resource path, only relevant if `className` is set.
  
  | `extensions`
  | _[]_
  | The list of extensions to add to the project (comma-separated)
  
  |===
  
  If you decide to generate a REST resource (using the `className` attribute), the endpoint is exposed at: `http://localhost:8080/$path`.
  If you use the default `path`, the URL is: http://localhost:8080/hello.
  
  The project is either generated in the current directory or in a directory named after the passed artifactId.
  If the current directory is empty, the project is generated in-place.
  
  A `Dockerfile` is also generated in `src/main/docker`.
  Instructions to build the image and run the container are written in the `Dockerfile`.
  
  == Dealing with extensions
  
  From inside a {project-name} project, you can obtain a list of the available extensions with:
  
  [source,shell]
  mvn quarkus:list-extensions
  
  You can enable an extension using:
  
  [source,shell]
  mvn quarkus:add-extension -Dextensions="hibernate-validator"
  
  Extensions are passed using a comma-separated list.
  
  == Development mode
  
  {project-name} comes with a built-in development mode.
  Run you application with:
  
  [source,shell]
  mvn compile 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 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 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.
  
  == Debugging
  
  You can run a {project-name} application in debug mode using:
  
  [source,shell]
  mvn compile quarkus:dev -Ddebug=true
  
  Then, attach your debugger to `localhost:5005`.
  
  == Import in your IDE
  
  Once you have a <<project-creation, project generated>>, you can import it in your favorite IDE.
  The only requirement is the ability to import a Maven project.
  
  **Eclipse**
  
  In Eclipse, click on: `File -> Import`.
  In the wizard, select: `Maven -> Existing Maven 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 `mvn compile quarkus:dev`, and enjoy a highly productive environment.
  
  **IntelliJ**
  
  In IntelliJ:
  
  1. From inside IntelliJ select `File -> New -> Project From Existing Sources...` or, if you are on the welcome dialog, select `Import project`.
  2. Select the project root
  3. Select `Import project from external model` and `Maven`
  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 `mvn compile quarkus:dev`. Enjoy!
  
  **Apache Netbeans**
  
  In Netbeans:
  
  1. Select `File -> Open Project`
  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 `mvn compile quarkus:dev`. Enjoy!
  
  **Visual Studio Code**
  
  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 Maven project.
  
  == Building a native image
  
  Native images make {project-name} applications ideal for containers and serverless workloads.
  
  Make sure to have `GRAALVM_HOME` configured and pointing to GraalVM version {graalvm-version}.
  Verify that your `pom.xml` has the proper `native` profile (see <<build-tool-maven>>).
  
  Create a native executable using: `mvn package -Pnative`.
  A native executable will be present in `target/`.
  
  To run Integration Tests on the native executable, make sure to have the proper Maven plugin configured (see <<build-tool-maven>>) and launch the `verify` goal.
  
  [source,shell]
  ----
  mvn package verify -Pnative
  ...
  [quarkus-quickstart-runner:50955]     universe:     391.96 ms
  [quarkus-quickstart-runner:50955]      (parse):     904.37 ms
  [quarkus-quickstart-runner:50955]     (inline):   1,143.32 ms
  [quarkus-quickstart-runner:50955]    (compile):   6,228.44 ms
  [quarkus-quickstart-runner:50955]      compile:   9,130.58 ms
  [quarkus-quickstart-runner:50955]        image:   2,101.42 ms
  [quarkus-quickstart-runner:50955]        write:     803.18 ms
  [quarkus-quickstart-runner:50955]      [total]:  33,520.15 ms
  [INFO]
  [INFO] --- maven-failsafe-plugin:2.22.0:integration-test (default) @ quarkus-quickstart-native ---
  [INFO]
  [INFO] -------------------------------------------------------
  [INFO]  T E S T S
  [INFO] -------------------------------------------------------
  [INFO] Running org.acme.quickstart.GreetingResourceIT
  Executing [/Users/starksm/Dev/JBoss/Protean/starksm64-quarkus-quickstarts/getting-started-native/target/quarkus-quickstart-runner, -Dquarkus.http.port=8081, -Dtest.url=http://localhost:8081, -Dquarkus.log.file.path=target/quarkus.log]
  2019-02-28 16:52:42,020 INFO  [io.quarkus] (main) Quarkus started in 0.007s. Listening on: http://localhost:8080
  2019-02-28 16:52:42,021 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy]
  [INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.081 s - in org.acme.quickstart.GreetingResourceIT
  [INFO]
  [INFO] Results:
  [INFO]
  [INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
  
  ...
  ----
  
  === Build a container friendly executable
  
  The native executable will be specific to your operating system.
  To create an executable that will run in a container, use the following:
  
  [source,shell]
  ----
  mvn package -Pnative -Dnative-image.docker-build=true
  ----
  
  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.
  
  You can follow the link:building-native-image-guide.html[Build a native image guide] as well as link:kubernetes-guide.html[Deploying Application to Kubernetes and OpenShift] for more information.
  
negative.code: <dependencyManagement>
      <dependencies>
          <dependency> <1>
              <groupId>io.quarkus</groupId>
              <artifactId>quarkus-bom</artifactId>
              <version>${quarkus.version}</version>
              <type>pom</type>
  