Getting Started with Gradle
In this tutorial, we’ll create a Gradle project, will run and test it, and run the executable JAR file using Gradle.
The project used in this tutorial can be found on GitHub.
Step 1. Create a project
Let’s create a Gradle project with Java.
Create a new Gradle Project with IntelliJ IDEA
On the welcome screen, click New Project .
On the page that opens, let’s specify our project’s name (FizzBuzz) and the location.
Let’s select the Java option, which is what we need for our project and Gradle since we are creating a Gradle project.
IntelliJ IDEA automatically adds a project SDK (JDK) in the JDK field. In our tutorial we use the open JDK 14 version.
You can change the selected JDK, IntelliJ IDEA will download the appropriate Gradle version. The only thing you need to have is the internet connection.
Let’s leave the default Groovy for Gradle DSL and unselect the Add sample code option since we’re going to add our own code from scratch.
We can use the default information for ArtifactId which basically is the name of our project and leave the default information in the GroupId field.
After we’ve created our project and it finished indexing, let’s see what is inside:
IntelliJ IDEA creates a project with the build.gradle file including the following code:
As you can see, IntelliJ IDEA conveniently adds a test dependency. IntelliJ IDEA supports code completion inside the build.gradle file. So, if we decide to add more dependencies, IntelliJ IDEA will quickly locate their names and versions.
IntelliJ IDEA also creates the src folder with main and test subdirectories in the Project tool window.
IntelliJ IDEA enables the dedicated Gradle tool window with a liked project and its default tasks. We will use this window to run our tasks.
If you closed this window, you can always access it from the main menu by selecting View | Tool Windows | Gradle .
The Gradle settings in our project are used to store the information about the linked projects, Gradle JVM, and build actions. You can quickly access them from the Gradle tool window (click on the toolbar).
As you can see, the build and test actions are delegated to Gradle. Also, the Gradle wrapper was used to determine Gradle for our project.
The project structure ( Ctrl+Alt+Shift+S ) contains information about the project’s JDK and a language level used in the project.
Step 2. Add Java code
Now let’s create a Java application that outputs the first 100 FizzBuzz numbers.
Add a Java class to the Gradle project
In the Project tool window open the src folder.
Click the main directory then right-click the java subdirectory and from the list select New | Package .
In the New Package dialog, let’s enter a name of our package which is com.gradle.tutorial .
Now right-click the package and select New | Java Class .
In the New Java Class dialog specify a name of your Java class and click OK . In our case it is FizzBuzzProcessor .
Add the following code to the main FizzBuzzProcessor class:
Our application is ready. Now, let’s create the necessary tests for it.
Create a test class
Open the main class FizzBuzzProcessor in the editor, place the caret at the class name and press Ctrl+Shift+T .
In the dialog that opens, let’s make sure that our testing library is JUnit4 (if you want use JUnit5 then make sure you have the JUnit5 ) and the destination package is com.gradle.tutorial . We add the name FizzBuzzTest and leave the rest of the default options as is and click OK .
Now open the created test class and add the following code:
Step 3. Run the application with Gradle
Let’s quickly run the application to see if it works.
Run main class from the editor
Open the main class FizzBuzzProcessor in the editor.
In the gutter, click and select Run ‘FizzBuzzProcessor.main()’ .
Check the result in the Run tool window.
Step 4. Run tests
Now, let’s run the test we’ve created.
Run tests in a Gradle project
We can run our test from the editor or from the Gradle tool window using the test task. We will use the editor.
Click in the gutter of the editor.
The result of the test will be displayed in the Run tool window.
If we change the default number in one of the tests, it will fail.
As you can see, the Run tool window displays information obout the failed test including the specific line of the code where the error occurred.
Step 5. Create an executable JAR file
Now let’s build our application to create an executable JAR file.
In the Project tool window, double click the build.gradle file to open it in the editor.
Add the following code:
Click in the editor to load the changes to your project.
In the Gradle tool window, open the project’s node, then the Tasks node and double-click the build task to run it.
IntelliJ IDEA creates the build directory that contains our JAR file.
You can run the created JAR file in the command line with java -jar command.
Check the Run tool window for the results.
Note that the build task includes the test task that Gradle executes. So, if we make a mistake in one of our tests, the test task will fail and the build task will fail as well.
Step 6. Run the JAR file with Gradle
Now let’s tweak the build.gradle file a little bit more, so we can execute our JAR file in the Run anything window.
Run the JAR file
In the Project tool window, double click the build.gradle file to open it in the editor.
Let’s add id ‘application’ to the plugins section and the following code:
Click in the editor to load the changes to your project.
In the Gradle tool window, open the project’s node, then the Tasks node. We can see that Gradle added the distribution node. Open the node and double-click the assembleDist task to run it.
If we check the build directory now, we’ll see that IntelliJ IDEA created additional directories.
In the Gradle tool window, click on the toobar.
In the window that opens, enter the gradlew run command.
We should have the same result as when we ran the application in the IntelliJ IDEA editor.
Gradle
IntelliJ IDEA supports a fully-functional integration with Gradle that helps you automate your building process. You can easily create a new Gradle project, open and sync an existing one, work with several linked projects simultaneously, and manage them.
You can also create a Gradle project and store it in the WSL environment or open it from the WSL file system. For more information, refer to the WSL section.
Create a new Gradle project
Launch the New Project wizard. If no project is currently opened in IntelliJ IDEA, click New Project on the welcome screen. Otherwise, select File | New | Project from the main menu.
Name the new project and change its location if necessary.
Select the Create Git repository to place the new project under version control.
You will be able to do it later at any time.
Select a language that you want to use in your project. Click if you want to add other languages available via plugins.
Select Gradle in the list of Build system .
Specify project’s SDK (JDK) or use the default one.
If you don’t have a JDK on your machine, IntelliJ IDEA can quickly download the JDK for you.
The Gradle project sync will wait until the JDK is downloaded.
The selected Add sample code option will create a file with a basic code sample.
Select Gradle DSL . You can select Groovy for traditional syntax or Kotlin as an alternative.
In Advanced Settings , specify the fields which resemble the Maven coordinates. These settings might be helpful if you decide to deploy your project to a Maven repository. The fields you specify are added to the build.gradle file.
GroupId — groupId of the new project. You can omit this field if you plan to deploy your project locally.
ArtifactId — artifactId that is added as a name of your new project.
Version — version of the new project. By default, this field is specified automatically.
For more information on Maven coordinates, see Maven naming conventions.
Create a Java EE project with Gradle as a build tool
Launch the New Project wizard. If no project is currently opened in IntelliJ IDEA, click New Project on the welcome screen. Otherwise, select File | New | Project from the main menu.
Under the Generators section, select Jakarta EE .
Configure your project selecting the appropriate options such as your project’s name, location, language, and select Gradle as your build tool.
IntelliJ IDEA creates a Gradle project with the dedicated Gradle tool window and adds necessary dependencies.
For the more detailed information, refer to Tutorial: Your first Java EE application.
Open an existing Gradle project
If you have the offline mode enabled in your project, the opening or re-importing of the project might fail. To fix the issue, disable the offline mode and re-import your project.
If no project is currently opened in IntelliJ IDEA, click Open on the welcome screen. Otherwise, select File | Open from the main menu.
If you have some custom plugins that require you to import your project from the IntelliJ IDEA model, press Ctrl+Shift+A and search for the Project from Existing Sources action.
In the dialog that opens, select a directory containing a Gradle project and click OK .
IntelliJ IDEA opens and syncs the project in the IDE.
If you need to adjust the Gradle settings options, refer to Gradle settings.
Check Gradle JVM and language level
Gradle JVM : when IntelliJ IDEA opens the Gradle project, it checks the gradle.properties file for the appropriate JVM version specified in org.gradle.java.home and uses it for the project. If it is not specified, then the project SDK is used. Alternatively, you can use the Gradle settings to configure the Gradle JVM.
Language level : the language level settings are applied for a source root or for a module. If a Gradle project has a single linked project then the project default language level is set to the minimum language level among the module language levels. The module language level is set to sourceCompatibility in the build.gradle file.
The preview part is set to the conjunction of preview flags of the module source sets. The source set module language level is set to the corresponding combination of sourceCompatibility property and —enable-preview flag.
Link a Gradle project to an IntelliJ IDEA project
You can have multiple Gradle projects inside one IntelliJ IDEA project. It might be helpful if you keep parts of code in different projects, have some legacy projects on which you need to work, have Gradle composite build or work with microservices. You can link such projects in IntelliJ IDEA and manage them simultaneously.
When you open a Gradle project, the link of the project is established automatically and the Gradle tool window is enabled.
If an IntelliJ IDEA project is not linked to a Gradle project, then the Gradle tool window is disabled. In this case, IntelliJ IDEA displays a message with a link that quickly lets you reimport your Gradle project and enable the Gradle tool window. If the Gradle tool window is active, then you have at least one Gradle project linked.
Open the Gradle tool window.
In the Gradle tool window, click to attach a Gradle project.
In the dialog that opens, select the desired build.gradle file, and click OK .
In the Import Module from Gradle window, specify options for the Gradle project that you are trying to link and click OK .
The project is linked. The Gradle tool window shows the toolbar and a tree view of Gradle entities.
If you need to link back the previously unlinked project, in the Project tool window, right-click the added build.gradle or if it is a Gradle Kotlin module the build.gradle.kts file and select Import Gradle Project .
Add a new Gradle module to an existing Gradle project
You can add a Gradle module to a project in which you are already working.
In a project, from the main menu, select File| New | Module to open the New Module wizard.
If the existing project is not the Gradle project then the process of adding a module is the same as Creating a new Gradle project. If the existing project is a Gradle project then the process of adding a new module is shorter. You need to specify the name of your module in the ArtifactId field. The rest of the information is added automatically and you can use either the default settings or change them according to your preferences. Also, note that Add as module to field, by default, displays the name of your project to which you are trying to add a module. You can click to select a different name if you have other linked Gradle projects.
Convert a regular project into a Gradle project
Open your project in IntelliJ IDEA.
In the Project tool window, right-click the name of your project and select New | File .
In the dialog that opens enter build.gradle and click OK .
Open the build.gradle file in the editor, add the information you need and re-open your project. The following minimal information should be included into the project’s build script file:
As soon as you create a build.gradle file, IntelliJ IDEA recognizes the Gradle build script and displays a notification suggesting to load the project as Gradle. After you load the project, IntelliJ IDEA enables the Gradle tool window.
We also recommend that you add the settings.gradle file to your project and add rootProject.name = ‘projectName’ to it. Where ‘projectName’ would be the name of your project.
Access the Gradle settings
Use the Gradle settings to configure the build and run actions for each linked Gradle project, a Gradle version, importing of the project’s changes, and so on.
In the Settings dialog ( Ctrl+Alt+S ), go to Build, Execution, Deployment| Gradle .
Click on the toolbar, in the Gradle tool window to access the Gradle settings.
On the Gradle settings page, configure the available options and click OK to save the changes.
Configure a Gradle version for a project
IntelliJ IDEA lets you use different options to configure a Gradle version for your Gradle project. You can use the default Gradle wrapper, use a Gradle wrapper as a task, or configure a local Gradle distribution.
Select in the Gradle tool window to quickly access the Gradle settings page.
In the Use Gradle from list select one of the following options:
‘gradle-wrapper.properties’ file : this is a recommended default option that uses Gradle wrapper.
In this case you delegate the update of Gradle versions to Gradle and get an automatic Gradle download for the build. This option also lets you build with a precise Gradle version. The Gradle version is saved in the gradle-wrapper.properties file in the gradle directory of your project and helps you eliminate any Gradle version problems.
‘wrapper’ task in Gradle build script : select this option to configure a Gradle wrapper according to the wrapper task configuration. It might be convenient if you prefer to control which Gradle version to use in the project.
If you used the default Gradle wrapper option and then switched to the Gradle wrapper task configuration, changes you made in the task automatically update during the project import.
Specified location : select this option if you want to manually download and use a specific Gradle version. Specify the location of your Gradle installation and JVM under which IntelliJ IDEA will run Gradle when you import the specified Gradle project and when you execute its tasks.
Click OK to save the changes.
Add VM options for the Gradle project
You can specify VM options for your Gradle project using the gradle.properties file.
Create or open your Gradle project.
In the Project tool window, right-click the project and from the context menu, select New | File .
In the New File dialog, enter gradle.properties as a filename and click OK .
Open the created file in the editor and add the VM options you need.
For more information, refer to the Gradle documentation.
Increase daemon heap size
You can adjust the existing Gradle daemon heap size for your project using the gradle.properties file.
Create or open your Gradle project.
In the Project tool window, right-click the project and from the context menu, select New | File .
Developing an Intellij IDEA Plugin for a Custom Language — Tutorial 2-Creating a Gradle project for plugin and initial steps in developing the actual plugin
In this article i will be considering on creating a Gradle project for plugin and implementing the file type recognition. Let’s consider Sample is the name of our custom language and the file extension for the language is .sample. I used gradle in the project because it is really easy to configure and do the necessary changes later in the project.
1. Creating the Gradle project
Click Create New Project or File -> New -> Project and select Gradle.
Provide a GroupId and ArtifactId.
Provide the Gradle home. If you haven’t installed gradle follow steps given here.
Provide the project name and project location.
After above steps you will get the following project structure.
Then click File ->Project Structure and select Project tab and provide the Project SDK we created in Tutorial 01.
2. Adding File Type Recognition feature
2.1 Update the build.gradle file
To run the plugin project we need to configure ‘run configuration’. So we need to add intellij gradle plugin to the file which helps to build and run the plugin inside a intellij IDEA instance. After updating build.gradle it should look like this.
2.2 Define the language — SimpleLanguage.java
In here we define our language which is ‘Simple’. To do this we need to extend the Language class which is the base class for all programming language support implementations. Specific language implementations should inherit from this class.
2.3 Define an icon — SimpleIcons.java
In here we define a default icon for our language. For this i got a free icon from here. You should place this icon in the SimplePlugin/src/main/resources/icons path. Then intellij IDEA will automatically detect it as a resource. (refer to the screenshot)
2.4 Define a file type — SimpleFileType.java
In here we define the file type and other related details to the plugin.
2.5 Define a file type factory— SimpleFileTypeFactory.java
This is used when a creating an instance of a file type associated to the Simple language.
2.6 Define the plugin.xml file
We need to define a file named plugin.xml in SimplePlugin/src/main/resources/META-INF/plugin.xml .(refer screenshot)
2.7 Update the plugin.xml with file type factory extension
We need to add the file type factory implementation location to the plugin.xml file. For this we declare the implementation inside <extensions></extension>
2.8 Build and run the plugin project
Click the runIde task in the gradle window and run the plugin. It will start a intellij IDEA instance with the simple plugin installed.
To test the file type association we need to create a project. Since we haven’t created a specific project type for our simple language yet, for the moment let’s create a java project.
Then create a file with the extension .simple .
If you have followed all the above steps correctly, then you will see the icon you have provided earlier for the Simple language will be shown before the name of the file you created.
Hurrah! You have done the tutorial successfully. The source code foe this can be found in this github link.
My next tutorial will be on Implementing Syntax Highlighting for a custom language.
Gradle tutorial
Gradle is a build automation tool used to automate build processes. There are many ways of integrating Gradle into a project. This tutorial uses the Gradle wrapper approach.
Basics
You use a build file (named build.gradle ) to describe the project to Gradle. A build file mainly consists of plugins, tasks and properties.
Plugins extend the functionality of Gradle. For example, the java plugin adds support for Java projects.
Tasks are reusable blocks of logic. For example, the task clean simply deletes the project build directory. Tasks can be composed of, or dependent on, other tasks.
Properties change the behavior of tasks. For instance, mainClassName of the application plugin is a compulsory property which tells Gradle which class is the entry point to your application. As Gradle favors convention over configuration, there is not much to you need to configure if you follow the recommended directory structure.
Gradle within Intellij: an overview
The following video (from the Intellij team) gives a quick overview of various ways Gradle can be used within Intellij. A quick watch of it may be useful before diving into specific use cases explained in the subsequent sections in this page.
Adding Gradle to the project
Scenario 1: You are setting up a project in Intellij IDEA. The project already has Gradle support.
If the project comes with Gradle support, you will see a build.gradle file in your project root.
- Open Intellij (if you are not in the welcome screen, click File > Close Project to close the existing project first)
- Open the project into Intellij as follows:
- Click Open .
- Select the project directory, and click OK .
- If there are any further prompts, accept the defaults.
Scenario 2: You are adding Gradle support to an ongoing project that is already set up in Intellij IDEA. Gradle wrapper files have been provided.
- Add the Gradle wrapper files to the project. e.g., if they are in a separate branch, merge that branch.
- Close the IDEA project if it is open.
- Delete the .idea folder.
- Open/import the project again, as explained in scenario 1 above.
Scenario 3: You are adding Gradle support to an ongoing project from scratch.
-
is a good place to start.
Using Gradle in Intellij IDEA
If the Gradle tasks don’t appear in the Gradle window, click the ‘refresh’ button in the toolbar to reimport the Gradle project.
Intellij uses Gradle to run your application by default. If you would like to run the project in the normal way, go to File > Settings and change the following settings:
Running Gradle Tasks
To run a task, locate the task in the Gradle toolbar, right-click on a task, and choose run .
Alternatively, you can type the command in the terminal.
- On Windows: gradlew <task1> <task2> … e.g. gradlew clean test
- On Mac/Linux: ./gradlew <task1> <task2> … e.g. ./gradlew clean test
Adding plugins
Gradle plugins are reusable units of build logic. Most common build tasks are bundled into core plugins provided by Gradle. Java, Checkstyle, and Shadow are three of plugins commonly used in Java projects. The relevant lines of the build.gradle are given below:
Using Gradle to do some common project activities
Cleaning the project
- clean : Deletes the files created during the previous build tasks (e.g. files in the build folder).
e.g. ./gradlew clean
You can use clean to prevent Gradle from skipping tasks: When running a Gradle task, Gradle will try to figure out if the task needs running at all. If Gradle determines that the output of the task will be same as the previous time, it will not run the task. For example, it will not build the JAR file again if the relevant source files have not changed since the last time the JAR file was built. If you want to force Gradle to run a task, you can combine that task with clean (e.g., ./gradlew clean shadowJar ). Once the build files have been clean ed, Gradle has no way to determine if the output will be same as before, and it will have no choice but to execute the task.
Running Checkstyle
gradlew checkstyleMain checkstyleTest : runs main code and test code complies with the Checkstyle rules.
Resources:
Running tests
Run the test task to run the tests in the project.
Resources:
Creating JAR files
Shadow is a plugin that packages an application into an executable fat jar file if the current file is outdated.
Tutorials → Working with JAR files → Fat JAR files
The task shadowJar (e.g., running the command gradlew shadowJar or gradlew clean shadowJar ) creates the JAR file in the build/libs folder. By default, it produces a jar file with the name in the format of
— .jar and put it in the builds/libs folder. These properties can be set in the build.gradle file. Ensure your build.gradle file contains the correct values w.r.t. the Shadow plugin e.g., mainClassName
If you are using JavaFX, see the panel below to find what else you need to add to the build.gradle to pack JavaFX libraries into the generated JAR file.
Tutorials → JavaFX Tutorial Part 1 → If you are using Gradle
Resources:
Compiling
There is no need to run these Gradle tasks manually as they are called automatically by other relevant Gradle tasks.
- compileJava : Checks whether the project has the required dependencies to compile and run the main program, and download any missing dependencies before compiling the classes. See build.gradle → allprojects → dependencies → compile for the list of dependencies required.
- compileTestJava : Checks whether the project has the required dependencies to perform testing, and download any missing dependencies before compiling the test classes. See build.gradle → allprojects → dependencies → testCompile for the list of dependencies required.
Enabling assertions
To enable assertions when executing Java code, add the following to the build.gradle file.
Managing dependencies
Gradle can automate the management of dependencies to third-party libraries. You just need to add the dependency into the build.gradle file and Gradle will do the rest. For example, here is how the JUnit library has been added to the dependencies in the build.gradle :
For example, to add the Natty (a third-party library used for parsing natural language dates e.g., today ), you simply have to add the following line to the dependencies section of the build.gradle file.
Tip: Most third-party libraries specify how to add it as a Gradle dependency (example).