IntelliJ IDEA 2017.1 Help

Gradle

Creating a new Gradle project or a module

  1. Launch the New Project wizard. If no project is currently opened in IntelliJ IDEA, click Create New Project on the Welcome screen: Otherwise, select File | New | Project from the main menu.
  2. In the left-hand pane, select Gradle.
  3. In the right-hand pane, specify the following options:
    • Project SDK - specify your project SDK (JDK).
      If the necessary JDK is already defined in IntelliJ IDEA, select it from the list. Otherwise, click New and select the installation folder of the desired JDK.
    • Additional Libraries and Frameworks - use this area to select an additional framework or a library for your Gradle project. IntelliJ IDEA adds the appropriate plugin to the build.gradle file.
    Click Next.
  4. On the next page of the wizard, IntelliJ IDEA displays fields which names resemble the ones that are used in Maven naming conventions. It might be helpful if you want to deploy your project to a Maven repository. You can select the following options:
    • GroupId - use this field to specify groupId of the new project, which will be added to the build.gradle file. If a parent Gradle project is specified, this coordinate can be inherited from the parent. To do that, select the Inherit check box. You can omit this field if you plan to deploy your project locally.
    • ArtifactId - use this field to specify artifactId that is added as a name of your new project and will be displayed in the build.gradle file.
    • Version - use this field to specify version of the new project, which will be added to the build.gradle file. By default, this field is specified automatically. If a parent Gradle project is specified, this coordinate can be inherited from the parent. To do that, select the Inherit check box.
    Click Next.
  5. On the next page of the wizard, specify the following Gradle settings:
    • Use auto-import - select this check box to resolve all changes made to the Gradle project automatically every time you refresh your project.
    • Create directories for empty content roots automatically - select this check box to create a default directory structure for a Gradle project, e.g. /src/main/java and /src/test/java.
    • Create separate module per source set - select this check box to use the source sets feature in resolving your Gradle projects.
    • Use default gradle wrapper (recommended) - select this option to use Gradle wrapper. Using the Gradle wrapper lets you get automatic Gradle download for the build. It also lets you build with the precise Gradle version.
    • Use local gradle distribution - select this option to use your local Gradle installation.
    • Gradle home - use this field to specify the fully qualified path to your Gradle installation. This field becomes active when you select Use local gradle distribution.

      If Gradle location has been defined by the environment variables GRADLE_HOME or PATH, then IntelliJ IDEA deduces this location, and suggests this path as the default value.

      If Gradle location has not been deduced from the environment variables, specify it manually, or click the Browse button, and select the desired directory in the dialog that opens. Note that the value entered in this field takes precedence over the environment variables.

    • Gradle JVM - use this drop-down list to specify JVM under which IntelliJ IDEA will run Gradle when you import the specified Gradle project and when you execute its tasks.
    Click Next.
  6. Specify the name and location settings. For more information, see Project Name and Location or Module Name and Location.
    Click Finish.

Adding a new Gradle module to an existing project

You can add a Gradle module to the project in which you are already working.

  1. In a project, on the main menu, select File| New | Module to open New Module wizard.
  2. 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 the 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 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 /help/img/idea/2017.1/moduleFolder.png to select a different name if you have other linked Gradle projects.

Importing a Project from a Gradle Model

  1. Launch the New Project wizard. If no project is currently opened in IntelliJ IDEA, click Import Project on the Welcome screen. Otherwise, select File | New | Project from Existing Sources from the main menu.

    Note that you can also select File | Open from the main menu and choose build.gradle file or a directory containing build.gradle file. IntelliJ IDEA will import a Gradle project even if the project was not opened or imported before.

  2. In the dialog that opens, select the directory that contains the project you want to import or a file that contains a Gradle project description (build.gradle). Click OK.
  3. On the first page of the Import Project wizard, in the Import Project from External model select Gradle and click Next.

    (This page is not displayed if IntelliJ IDEA has guessed what you are importing.)

  4. On the next page of the Import Project wizard, specify the following settings:
    • Gradle project settings that are the same as in Gradle.
    • Global Gradle settings that are as follows:
      • Offline work - use this check box to work with Gradle in the offline mode. In this case Gradle will use dependencies from the cache. Gradle will not attempt to access the network to perform dependency resolution. If required dependencies are not present in the dependencies' cache, a build execution will fail.
      • Service directory path - use this field to override the default Gradle home location directory.
      • Gradle VM options - use this field to specify VM options for your Gradle project.
    Click Finish.

Importing a Gradle Module

  1. You can start your module's import in one of the following ways:
    • From the main menu, select File | New | Module from Existing Sources.
    • In the Project Structure dialog, on the Module page, click /help/img/idea/2017.1/add.png icon and select Import Module.
    • In the Gradle tool window, on the toolbar, click /help/img/idea/2017.1/gradle_data_to_import_icon.png icon.
  2. In the dialog that opens, select a module you want to import and click OK.
  3. If necessary perform steps described in the Importing a Gradle project section and click Finish.
  4. If you have a multi-module project the Select Project Data to Import dialog opens.
    In the Select Project Data to Import dialog, select modules or data you want to include in your project and click OK.

Working with Gradle projects

IntelliJ IDEA lets you manage Gradle projects. You can open, link, configure the Gradle composite build, and synchronize changes of your Gradle project with IntelliJ IDEA project.

Linking a Gradle project to IntelliJ IDEA project

When a project is created by importing from Gradle model, this link is established automatically and the Gradle Projects 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 import your Gradle project and enable the Gradle Projects tool window.
If the Gradle Projects tool window is active then you have at least one Gradle project linked.

  1. Open Gradle Projects tool window.
  2. In the Gradle Projects tool window, click /help/img/idea/2017.1/new.png to attach a gradle project.
  3. In the dialog that opens, select the desired build.gradle file, and click OK.
  4. 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 Projects tool window shows the toolbar and a tree view of Gradle entities.

Alternatively, you can link your Gradle project if you import your project as a Gradle module from the existing sources. In this case, you can link your Gradle project even if the Gradle Projects tool window is not available.

Navigating to the build.gradle file

  1. In the Gradle Projects tool window, right-click on the linked project.
  2. From the context menu select /help/img/idea/2017.1/icon_gradle.png.

    IntelliJ IDEA navigates to the appropriate Gradle configuration file and the related build.gradle file opens in the editor.

Detaching or ignoring a linked Gradle project

  1. In the Gradle Projects tool window, right-click on the linked project.
  2. From the context menu, select /help/img/idea/2017.1/delete.png (Delete ). Alternatively, you can select the linked project and click /help/img/idea/2017.1/delete.png on the Gradle tool bar.
  3. In the Import Gradle Projects pop-up window, clear the check box against the modules if you don't want to delete the project from the IntelliJ IDEA project's view.
  4. Click OK.

    The Gradle project is detached from the IntelliJ IDEA project and is not synchronized any more.

You can also de-activate Gradle project using Ignore Gradle Project option.

  1. In the Gradle Projects tool window, right-click the project that you want to ignore.
  2. In the context menu, select Ignore Gradle Project.
  3. In the window that opens, select projects and modules that you want to de-activate and click OK.

    In this case IntelliJ IDEA removes the selected projects and modules from the IntelliJ IDEA project's view and will not import them any more. However, you still are able to see the list of ignored Gradle modules and projects in the Gradle Projects tool window.

    If you want to activate your Gradle projects or modules, select Unignore Gradle Projects from the context menu.

Refreshing a linked Gradle project

  1. In the Gradle tool window, right-click on the linked project.
  2. From the context menu, select /help/img/idea/2017.1/refresh.png.

    On pressing this button, IntelliJ IDEA parses the project structure in the Gradle Projects tool window.

    Note that if you configure a dependency through the Project Structure dialog, the dependency will only appear in the IntelliJ IDEA Project tool window, not in the Gradle tool window. Also, note that the next time you refresh your project, IntelliJ IDEA will remove the added dependency since IntelliJ IDEA considers the Gradle configuration as a single source of truth.

Configuring Gradle Composite Build

Before you start configuring your composite build, make sure you have the Gradle version 3.1 or higher configured for your project.

Also, note that there are some restrictions on using Gradle composite build.

You can use settings.gradle file to include Gradle builds for your Gradle composite build.

  1. Open the settings.gradle file in the editor.
  2. Using includeBuild command, specify the location of the builds you want to add as dependencies to you project.

You can also use the Gradle Projects tool window to configure your composite build.

  1. Open your Gradle project.
  2. Link other Gradle projects that you want to use for your composite build.
  3. In the Gradle Projects tool window, right-click your main project and from the context menu select Composite Build Configuration.
  4. In the Gradle Project Build Composite dialog, select projects that you want to include in your Gradle composite build.
  5. Refresh your main Gradle project.

    IntelliJ IDEA finds the included Gradle projects and treats them as IntelliJ IDEA modules.

Working with Gradle tasks

IntelliJ IDEA lets you create run/debug configuration, select and run Gradle tasks different ways, debug them and assign shortcuts to your Gradle tasks.

Running a Gradle task from the Gradle tool bar

  1. In the Gradle projects tool window, on the tool bar, click /help/img/idea/2017.1/gradle_icon.png.
  2. In the Run Gradle Task dialog, in the Command line field, start entering the name of your task. You can see that IntelliJ IDEA displays the list of Gradle tasks from which you can select the appropriate one. Click OK.
    /help/img/idea/2017.1/gradle_run_task_from_toolbar.png
  3. IntelliJ IDEA runs the selected task and displays the result in the Run tool window.
    /help/img/idea/2017.1/gradle_task_run_result.png
    IntelliJ IDEA also saves the task in Gradle Projects under the Run Configurations node.
    /help/img/idea/2017.1/gradle_run_config_task_save.png

Running a Gradle task via Run Configurations

  1. Right-click the task for which you want to create the Run configuration.
  2. From the drop-down list select Create 'task name'.
    /help/img/idea/2017.1/gradle_run_config_create.png
  3. In the Create Run/Debug Configuration: 'task name', specify the settings for your task and click OK.
    /help/img/idea/2017.1/run_debug_gradle_task.png
    IntelliJ IDEA displays the task under the Run Configurations node.
    /help/img/idea/2017.1/gradle_run_config_task_display.png
  4. Double-click the task to run or right-click the task and from the context menu select Run.
    /help/img/idea/2017.1/gradle_config_task_run.png

Running a Gradle task from the context menu

  1. Right-click the task that you want to run.
  2. From the context menu select Run 'task name'.
    /help/img/idea/2017.1/gradle_task_run_from_menu.png

Running several Gradle tasks with one Run/Debug configuration

  1. Select Run | Edit Configurations (Shift+Alt+F10).
    The Run/Debug Configurations dialog opens.
  2. In the Run/Debug Configurations dialog, click /help/img/idea/2017.1/add.png icon and select Gradle to add a new configuration.
    /help/img/idea/2017.1/gradle_run_debug_config_add.png
  3. On the right side of the Run/Debug Configurations dialog, in the Name field, specify the name of your configuration.
    Let's also specify the following settings:
    • Gradle project - click /help/img/idea/2017.1/gradle_registered_projects_button.png and select the registered Gradle project.
      /help/img/idea/2017.1/gradle_select_registered_project.png
    • Tasks - specify tasks you want to execute with this configuration. You can run more than one task.
      In our case let's specify clean and build.
    • VM options - you can customize VM options. Let's specify -Xmx3g.
    • Arguments - you can specify Gradle command line parameters. For example, let's specify --debug.
    /help/img/idea/2017.1/gradle_run_debug_config_settings.png
  4. Click OK.
    The created Run/Debug configuration is added to the Run Configurations node in the Gradle Projects tool window and is treated as a Gradle task.
  5. Double-click the configuration or right-click the configuration and select Run to execute the task.
    /help/img/idea/2017.1/gradle_run_configuration.png

Debugging Gradle tasks in the Gradle projects tool window

Tasks available for debugging via the Gradle projects tool window are the ones that implement org.gradle.process.JavaForkOptions interface. For example, test or run. For debugging Gradle script tasks themselves, use a Groovy run/debug configuration that appears in the context menu when you right-click on the script task in the editor.

  1. In the Gradle projects tool window, in Tasks area, double-click on the Gradle project.

    The list of tasks opens.

  2. In the list of tasks, select a task which you want to debug, right-click on it and from the context menu select Debug option.

    The debugging process is started and the task is added to the list of recent tasks located under the Run Configurations node.

Assigning a shortcut to a Gradle task

IntelliJ IDEA lets you assign shortcuts to Gradle tasks that can be run in several different ways and execute those tasks with a single key-stroke. You can also assign a shortcut to the Gradle Run/Debug configuration that can contain more than one task.

  1. In the Gradle projects tool window, right-click the desired task.
  2. From the context menu, choose Assign Shortcut.
    /help/img/idea/2017.1/gradle_assign_shorcut.png
    The Keymap dialog opens.
  3. In the Keymap dialog, under the Gradle node you will see your task.
    /help/img/idea/2017.1/gradle_task_in_keymap_dialog.png
  4. Right-click the task and from the list that opens, select the type of the shortcut you want to assign.
    /help/img/idea/2017.1/gradle_add_shorcut_options.png
  5. In the dialog that opens, depending on the shortcut's type, configure the shortcut and click OK.
    In our case let's add the keyboard shortcut.
    /help/img/idea/2017.1/gradle_keyboard_shortcut.png
    You can see that the shortcut is displayed against your task in the Gradle Projects tool window.
    /help/img/idea/2017.1/gradle_shortcut_displayed.png

While in the Keymap dialog, you can add a new task to which you want to assign a shortcut.

  1. In the Keymap dialog, under the Gradle node, click Choose a task to assign a shortcut.
    /help/img/idea/2017.1/gradle_choose_task_while_in_keymap_dialog.png
  2. In the dialog that opens, select a task you need and click OK.
    /help/img/idea/2017.1/gradle_select_task_keymap.png
    The task is added to the list under the Gradle node. Now you can configure the shortcut.

Configuring and using a Gradle test runner

IntelliJ IDEA lets you use different test runners to execute tests in a Gradle project. You can use JUnit to run your tests, delegate the testing process to Gradle, or decide which test runner to use specifically per each test.

  1. In the Gradle Projects tool window, select /help/img/idea/2017.1/settings.png icon.
  2. In the Settings dialog, right-click Gradle and from the drop-down list, select Runner.
  3. On the page that opens, in the Run test using drop-down list, select an option that you want to use for your test run.
    /help/img/idea/2017.1/gradle_test_runner.png
    (The default value is Platform Test Runner.)
  4. Click OK.
  5. In your Gradle project, in the editor, create or select a test that you want to run.
  6. From the context menu, select Run <test name>.
    Alternatively, click /help/img/idea/2017.1/run.png icon in the left gutter.
    /help/img/idea/2017.1/gradle_run_test_gutter.png
  7. Depending on what you chose as your test runner option, IntelliJ IDEA runs your tests in one of the following ways:
    • If you selected Platform Test Runner, IntelliJ IDEA runs tests using a JUnit test runner and displays the output in the Run JUnit tool window.
      /help/img/idea/2017.1/platform_test_runner_output.png
    • If you selected Gradle Test Runner, IntelliJ IDEA runs tests using a Gradle test runner and displays the output in the Run Gradle tool window.
      /help/img/idea/2017.1/gradle_test_runner_output.png
    • If you selected Let me choose per test, IntelliJ IDEA lets you choose between JUnit or Gradle to run your test.
      /help/img/idea/2017.1/gradle_choose_per_test.png
      Once, you select the test runner, IntelliJ IDEA will remember your selection and automatically will run your test using the option you've chosen.
    You can change your selection, in the Runner settings page.

See Also

Language and Framework-Specific Guidelines:

External Links:

Last modified: 18 July 2017