This spec defines a number of features to improve the developer IDE experience with Gradle. It covers changes in Gradle to improve those features that directly affect the IDE user experience. This includes the tooling API and tooling models, the Gradle daemon, and the Gradle IDE plugins (i.e. the plugins that run inside Gradle to provide the IDE models).

This spec does not cover more general features such as improving dependency resolution or configuration performance.

Implementation plan

Below is a list of stories, in approximate priority order:

Feature - Improve IDE project naming deduplication strategy

Motivation

If we got a project structure like this:

:foo:app
:bar:app
:foobar:app

it currently results in the following eclipse project names:

app
bar-app
foobar-app

This behaviour can be quite confusing in the IDE. To make things clearer the deduplication strategy should be changed in a way that it results in:

foo-app
bar-app
foobar-app

Implementation Plan

The general algorithm will look like this:

if no duplicate of project name is found in the hierarchy, use the original name as IDE project name
root project name keeps the original name in IDE
if a project with the same name is found

3.1 the IDE project name candidate is changed to be deduplicated project.parent.name + - + project.name

3.2 duplicate words in the IDE project name candidate are removed.( eg gradle-gradle-core becomes gradle-core

3.3 skip 3.2 for identical parent and child project name
deprecate setting ide project name in whenMerged/beforeMerged hook.

Test Coverage

gradle eclipse / gradle idea on root of multiproject with given project layout containing duplicate names:

    root
    \- foo
       \- app
    \- bar
       \- app

results in IDE project names

    root
    \- foo
       \- foo-app
    \- bar
       \- bar-app

gradle eclipse / gradle idea on root of multiproject with given project layout containing with no duplicate names:

    root
    \- foo
       \- bar
    \- foobar
       \- app

results in IDE project names

    root
    \- foo
       \- bar
    \- foobar
       \- app

explicit configured IDE project name take precedence over deduplication: given

     root
     \- foo
        \- app
           \-build.gradle // contains e.g. eclipse.project.name = "custom-app" / ideaModule.module.name = "custom-app"
     \- bar
        \- app

results in

     root
     \- foo
        \- custom-app
     \- bar
        \- app

given project layout

    app
    \- app
    \- util

results in

    app
    \- app-app
    \- util

given project layout

    root
    \- app
    \- services
       \- bar
          \- app

results in

    root
    \- root-app
    \- services
       \- bar
          \- bar-app

given project layout

    myproject
    \- myproject-app
    \- myproject-bar
       \- myproject-app

results in

    myproject
    \- myproject-app (instead of myproject-myproject-app)
    \- myproject-bar
       \- myproject-bar-app (instead of myproject-bar-myproject-app)

deduplication logics works with deduplicated parent module name. given project layout:

   root
    \- bar
        \- services
            \- rest
    \- foo
            \- services
                \- rest

results in

    root
    \- bar
        \- bar-serivces
            \- bar-services-rest
    \- foo
        \- foo-serivces
            \- foo-services-rest

setting ide project name within whenMerged results in a deprecation warning.
setting ide project name within beforeMerged results in a deprecation warning.
tests work with IDE gradle plugins and with IDE model queried via tooling api

Feature - Tooling API parity with command-line for task visualisation and execution

This feature exposes via the tooling API some task execution and reporting features that are currently available on the command-line.

Task selection by name, where I can run gradle test and this will find and execute all tasks with name test in the current project and its subprojects. However, this selection logic does have some special cases. For example, when I run gradle help or gradle tasks, then the task from the current project only is executed, and no subproject tasks are executed.
Task reporting, where I can run gradle tasks and this will show me the things I can run from the current project. This report, by default, shows only the public interface tasks and hides the implementation tasks.

The first part of this feature involves extracting the logic for task selection and task reporting into some reusable service, that is used for command-line invocation and exposed through the tooling API. This way, both tools and the command-line use the same consistent logic.

The second part of this feature involves some improvements to the task reporting, to simplify it, improve performance and to integrate with the component model introduced by the new language plugins:

Task reporting treats as public any task with a non-empty group attribute, or any task that is declared as a public task of a build element.
All other tasks are treated as private.
This is a breaking change. Previously, the reporting logic used to analyse the task dependency graph and treated any task which was not a dependency of some other task as a public task. This is very slow, requires every task in every project to be configured, and is not particularly accurate.

Open issues

Split gradle tasks into 'what can I do with this build?' and a 'what are all the tasks in this project?'.

GRADLE-2434 - IDE visualises and runs task selectors (DONE)

On the command-line I can run gradle test and this will find and execute all tasks with name test in the current project and all its subprojects.

Expose some information to allow the IDE to visualise this and execute builds in a similar way.

See tooling-api-improvements.md

IDE hides implementation tasks (DONE)

On the command-line I can run gradle tasks and see the public tasks for the build, and gradle tasks --all to see all the tasks.

Expose some information to allow the IDE to visualise this.

See tooling-api-improvements.md

Simplify task visibility logic

Change the task visibility logic introduced in the previous stories so that:

A task is public if its group attribute is not empty.
A task selector is public if any of the tasks that it selects are public.

Test cases

Tooling API and gradle tasks treats as public a task with a non-empty group attribute.
Tooling API and gradle tasks treats as public a selector that selects a public task.
Tooling API and gradle tasks treats as private a task with null group attribute.
Tooling API and gradle tasks treats as private a selector that selects only private tasks.

Expose the lifecycle tasks of build elements as public tasks

Change the task visibility logic so that the lifecycle task of all BuildableModelElement objects are public, regardless of their group attribute.

Test cases

Tooling API and gradle tasks treats as public the lifecycle task of a BuildableModelElement with a null group attribute.

Open issues

Should other tasks for a BuildableModelElement be private, regardless of group attribute?

GRADLE-2017 - Correctly map libraries to IDEA dependency scope

A new model will be available for defining IDEA scopes: these scopes will formed by combining and excluding Gradle configurations and other scopes. The model can statically restrict the available scopes to 'compile', 'runtime', 'provided' and 'test'.

Model

Introduce a model for binaries that run on the JVM and that are built locally:

interface Classpath { // This type already exists
    ...
    libs(Object) // Adds libraries to this classpath
}

interface JvmPlatform {
    Classpath compile
    Classpath runtime
}

interface JvmBinary {
    JvmPlatform platform
    Classpath compile
    Classpath runtime
}

interface MainJvmBinary extends JvmBinary {
    JvmBinary tests
}

The Java base plugin registers an implementation of MainJvmBinary, and the Java and WAR plugins fill it in so that:

configurations.compile is added to jvmBinary.compile
configurations.runtime is added to jvmBinary.runtime
configurations.testCompile is added to jvmBinary.test.compile
configurations.testRuntime is added to jvmBinary.test.runtime
configurations.providedCompile is added to jvmBinary.platform.compile
configurations.providedRuntime is added to jvmBinary.platform.runtime

Introduce IDEA scope model:

interface IdeaScope {
    String name
    List<Dependency> libraries // read-only, calculated on demand
}

interface IdeaScopes {
    IdeaScope provided
    IdeaScope compile
    IdeaScope runtime
    IdeaScope test
}

class IdeaModule { // this type already exists
    ...
    IdeaScopes ideaScopes
}

The IDEA plugin calculates the contents of the scopes based on the JvmBinary model defined above:

scope provided should contain jvmBinary.platform.compile
scope compile should contain jvmBinary.compile minus scope provided.
scope runtime should contain (jvmBinary.runtime union jvmBinary.platform.runtime) minus scope compile.
scope test should contain (jvmBinary.test.compile minus scope compile) union (jvmBinary.test.runtime minus scope runtime).

An example customisation:

binaries {
    jvm {
        test.compile configurations.integTestCompile
        test.runtime configurations.integTestRuntime

        platform.compile configurations.myCustomProvided
    }
}

TODO: Example DSL

The new DSL (and model defaults) will be used to configure an IDEA module when the current scopes map has not been altered by the user. Once the new DSL is stabilised we will deprecate and remove the scopes map.

Implementation

Add ResolvableComponents which represents a set of requirements that can be resolved into a graph or set of Components
Add an implementation of ResolvableComponents that wraps a Configuration instance
Add an implementation of ResolvableComponents that can combine other ResolvableComponents as required for the Idea scope DSL
Update each method on IdeDependenciesExtractorso that it takes a ResolvableComponents parameter in place of the current Collection<Configuration> plusConfigurations, Collection<Configuration> minusConfigurations.
- For now, these methods can simply unpack the ResolvableComponents to a set of added and excluded configurations.
- The current scope map DSL should be mapped to the new API
Add domain classes as required for the new Idea scopes DSL, with appropriate defaults.

Test cases

When using the tooling API to fetch the IDEA model or the idea task to generate the IDEA project files, verify that:
- When a java project has a dependency declared for testCompile and runtime, the dependency appears with test and runtime scopes only.
- When a java project has a dependency declared for testRuntime and runtime, the dependency appears with runtime scope only.
- When a java project has a dependency declared for compile and testCompile, the dependency appears with compile scope only.
- When a war project has a dependency declared for providedCompile and compile, the dependency appears with provided scope only.
Current defaults are used when the scopes maps is configured by user.
User is informed of failure when both scopes map and new DSL are configured.

Open issues

Similar new DSL for the Eclipse model (except that it’s much simpler).
ArtifactResolutionQuery API takes a ResolvableComponents as input
- Include JvmLibrary main artifact in query results
- Replace IdeDependenciesExtractor.extractRepoFileDependencies with single ArtifactResolutionQuery

Feature - Tooling API client cancels an operation (DONE)

Add some way for a tooling API client to request that an operation be cancelled.

The implementation will do the same thing as if the daemon client is disconnected, which is to drop the daemon process. Later stories incrementally add more graceful cancellation handling.

See tooling-api-improvements.md

Feature - Expose dependency resolution problems

For the following kinds of failures:
- Missing or broken module version
- Missing or broken jar
- Missing or broken source and javadoc artifact
Change the IDE plugins to warn for each such problem it ignores, and fail on all others.
Change the tooling model include the failure details for each such problem.

Test coverage

Change the existing IDE plugin int tests to verify the warning is produced in each of the above cases.
Add test coverage for the tooling API to cover the above cases.

Feature - Expose build script compilation details

See tooling-api-improvements.md:

Expose some details to allow some basic content assistance for build scripts:

Expose the classpath each build script.
Expose the default imports for each build script.
Expose the Groovy version for each build script.

Story - Tooling API stability tests

Introduce some stress and stability tests for the tooling API and daemon to the performance test suite. Does not include fixing any leaks or stability problems exposed by these tests. Additional stories will be added to take care of such issues.

Feature - Daemon usability improvements

Story - Build script classpath can contain a changing jar

Fix ClassLoader caching to detect when a build script classpath has changed.

Fix the ClassLoading implementation to avoid locking these Jars on Windows.

Story - Can clean after compiling on Windows

Fix GRADLE-2275.

Story - Prefer a single daemon instance

Improve daemon expiration algorithm so that when there are multiple daemon instances running, one instance is selected as the survivor and the others expire quickly (say, as soon as they become idle).