From 125bc809cf6c4d66e021591bcb2dd01af669b2c4 Mon Sep 17 00:00:00 2001 From: Tom Gardiner Date: Thu, 23 Nov 2023 07:42:55 +1100 Subject: [PATCH] Update brief readme --- README | 264 +-------------------------------------------------------- 1 file changed, 1 insertion(+), 263 deletions(-) diff --git a/README b/README index daf9baeb..2ba333ff 100644 --- a/README +++ b/README @@ -1,263 +1 @@ -:samples-dir: /home/tcagent1/agent/work/64493a816be20d5a/promote-projects/gradle/build/git-checkout/subprojects/docs/build/working/samples/install/building-java-applications -:gradle-version: 8.1.1-20230420133545+0000 - -= Building Java Applications Sample - -[.download] -- link:zips/sample_building_java_applications-groovy-dsl.zip[icon:download[] Groovy DSL] -- link:zips/sample_building_java_applications-kotlin-dsl.zip[icon:download[] Kotlin DSL] - -NOTE: You can open this sample inside an IDE using the https://www.jetbrains.com/help/idea/gradle.html#gradle_import_project_start[IntelliJ native importer] or https://projects.eclipse.org/projects/tools.buildship[Eclipse Buildship]. - -This guide demonstrates how to create a Java application with Gradle using `gradle init`. -You can follow the guide step-by-step to create a new project from scratch or download the complete sample project using the links above. - - - -== What you’ll build - -You'll generate a Java application that follows Gradle's conventions. - -== What you’ll need - -* A text editor or IDE - for example link:https://www.jetbrains.com/idea/download/[IntelliJ IDEA] -* A Java Development Kit (JDK), version 8 or higher - for example link:https://adoptopenjdk.net/[AdoptOpenJDK] -* The latest https://gradle.org/install[Gradle distribution] - - -== Create a project folder - -Gradle comes with a built-in task, called `init`, that initializes a new Gradle project in an empty folder. -The `init` task uses the (also built-in) `wrapper` task to create a Gradle wrapper script, `gradlew`. - -The first step is to create a folder for the new project and change directory into it. - -[listing.terminal.sample-command] ----- -$ mkdir demo -$ cd demo ----- - -== Run the init task - -From inside the new project directory, run the `init` task using the following command in a terminal: `gradle init`. -When prompted, select the `2: application` project type and `3: Java` as implementation language. -Next you can choose the DSL for writing buildscripts - `1 : Groovy` or `2: Kotlin`. -For the other questions, press enter to use the default values. - -The output will look like this: - -[listing.terminal.sample-command,user-inputs="2|3|1|||"] ----- -$ gradle init - -Select type of project to generate: - 1: basic - 2: application - 3: library - 4: Gradle plugin -Enter selection (default: basic) [1..4] 2 - -Select implementation language: - 1: C++ - 2: Groovy - 3: Java - 4: Kotlin - 5: Scala - 6: Swift -Enter selection (default: Java) [1..6] 3 - -Select build script DSL: - 1: Groovy - 2: Kotlin -Enter selection (default: Groovy) [1..2] 1 - -Select test framework: - 1: JUnit 4 - 2: TestNG - 3: Spock - 4: JUnit Jupiter -Enter selection (default: JUnit 4) [1..4] - -Project name (default: demo): -Source package (default: demo): - - -BUILD SUCCESSFUL -2 actionable tasks: 2 executed ----- - -The `init` task generates the new project with the following structure: - -[source.multi-language-sample,kotlin] ----- -├── gradle // <1> -│ └── wrapper -│ ├── gradle-wrapper.jar -│ └── gradle-wrapper.properties -├── gradlew // <2> -├── gradlew.bat // <2> -├── settings.gradle.kts // <3> -└── app - ├── build.gradle.kts // <4> - └── src - ├── main - │ └── java // <5> - │ └── demo - │ └── App.java - └── test - └── java // <6> - └── demo - └── AppTest.java ----- - -[source.multi-language-sample,groovy] ----- -├── gradle // <1> -│ └── wrapper -│ ├── gradle-wrapper.jar -│ └── gradle-wrapper.properties -├── gradlew // <2> -├── gradlew.bat // <2> -├── settings.gradle // <3> -└── app - ├── build.gradle // <4> - └── src - ├── main - │ └── java // <5> - │ └── demo - │ └── App.java - └── test - └── java // <6> - └── demo - └── AppTest.java ----- - -<1> Generated folder for wrapper files -<2> Gradle wrapper start scripts -<3> Settings file to define build name and subprojects -<4> Build script of `app` project -<5> Default Java source folder -<6> Default Java test source folder - -You now have the project setup to build a Java application. - -== Review the project files - -The `settings.gradle(.kts)` file has two interesting lines: - -==== -include::sample[dir="kotlin",files="settings.gradle.kts[]"] -include::sample[dir="groovy",files="settings.gradle[]"] -==== -- `rootProject.name` assigns a name to the build, which overrides the default behavior of naming the build after the directory it's in. - It's recommended to set a fixed name as the folder might change if the project is shared - e.g. as root of a Git repository. -- `include("app")` defines that the build consists of one subproject called `app` that contains the actual code and build logic. - More subprojects can be added by additional `include(...)` statements. - -Our build contains one subproject called `app` that represents the Java application we are building. -It is configured in the `app/build.gradle(.kts)` file: - -==== -include::sample[dir="kotlin",files="app/build.gradle.kts[]"] -include::sample[dir="groovy",files="app/build.gradle[]"] -==== -<1> Apply the application plugin to add support for building a CLI application in Java. -<2> Use Maven Central for resolving dependencies. -<3> Use JUnit Jupiter for testing. -<4> This dependency is used by the application. -<5> Define the main class for the application. -<6> Use JUnit Platform for unit tests. - -The file `src/main/java/demo/App.java` is shown here: - -.Generated src/main/java/demo/App.java -[source,java] ----- -include::{samples-dir}/groovy/app/src/main/java/demo/App.java[] ----- - -The generated test, `src/test/java/demo/App.java` is shown next: - -.Generated src/test/java/demo/AppTest.java -[source,java] ----- -include::{samples-dir}/groovy/app/src/test/java/demo/AppTest.java[] ----- - -The generated test class has a single _JUnit Jupiter_ test. -The test instantiates the `App` class, invokes a method on it, and checks that it returns the expected value. - -== Run the application - -Thanks to the `application` plugin, you can run the application directly from the command line. -The `run` task tells Gradle to execute the `main` method in the class assigned to the `mainClass` property. - -[listing.terminal.sample-command] ----- -$ ./gradlew run - -> Task :app:run -Hello world! - -BUILD SUCCESSFUL -2 actionable tasks: 2 executed ----- - -NOTE: The first time you run the wrapper script, `gradlew`, there may be a delay while that version of `gradle` is downloaded and stored locally in your `~/.gradle/wrapper/dists` folder. - -== Bundle the application - -The `application` plugin also bundles the application, with all its dependencies, for you. -The archive will also contain a script to start the application with a single command. - -[listing.terminal.sample-command] ----- -$ ./gradlew build - -BUILD SUCCESSFUL in 0s -7 actionable tasks: 7 executed ----- - -If you run a full build as shown above, Gradle will have produced the archive in two formats for you: -`app/build/distributions/app.tar` and `app/build/distributions/app.zip`. - -== Publish a Build Scan - -The best way to learn more about what your build is doing behind the scenes, is to publish a link:https://scans.gradle.com[build scan]. -To do so, just run Gradle with the `--scan` flag. - -[listing.terminal.sample-command] ----- -$ ./gradlew build --scan - -BUILD SUCCESSFUL in 0s -7 actionable tasks: 7 executed - -Publishing a build scan to scans.gradle.com requires accepting the Gradle Terms of Service defined at https://gradle.com/terms-of-service. -Do you accept these terms? [yes, no] yes - -Gradle Terms of Service accepted. - -Publishing build scan... -https://gradle.com/s/5u4w3gxeurtd2 ----- - -Click the link and explore which tasks where executed, which dependencies where downloaded and many more details! - -== Summary - -That's it! You've now successfully configured and built a Java application project with Gradle. -You've learned how to: - -* Initialize a project that produces a Java application -* Run the build and view the test report -* Execute a Java application using the `run` task from the `application` plugin -* Bundle the application in an archive - -== Next steps - -To learn more about how you can further customize Java application projects, check out the following user manual chapters: - - - link:{userManualPath}/building_java_projects.html[Building Java & JVM projects] - - link:{userManualPath}/application_plugin.html[Java Application Plugin documentation] +IntegraBoost - Enhance your ability to write integration or e2e tests easily \ No newline at end of file