Skip to content

Migration guide from STS Gradle to Buildship

Jump to bottom
Etienne Studer edited this page Feb 16, 2016 · 7 revisions

Motivation

Gradle provides tooling integration capabilities which can be used to execute and monitor builds as well as to query the details of the build.

There are two major Gradle plugins for Eclipse: one created by SpringSource as part of the Spring Tool Suite and one called Buildship developed by Gradle Inc. Since Buildship became an eclipse.org project, the SpringSource developers are planning to phase out their tooling and switch to Buildship.

The purpose of this document is to provide a comparison between STS Gradle and Buildship and to give precise steps on how to migrate from one tool to another.

Differences between Buildship and STS Gradle

There are a few differences between the tools in terms of features. You should consider them before starting the migration.

Features only supported by Buildship

  • Full transitive closure of dependencies: Each project imported into Eclipse has a direct reference to all of its dependencies so that the classpath does not rely on what dependencies other modules export.
  • Execution visualization: The Executions view provides a visual overview of the build, the hierarchy of steps and the execution times.
  • Native test execution: Users can select a Java class or method from Java editor or from the Executions view and can launch it as Gradle test. It won't be executed by Eclipse's Junit launcher but instead Gradle will execute the test via the Tooling API test launcher functionality.

Features only supported by STS Gradle

  • Import task execution: Upon project import if a project configuration needs to be adjusted with Gradle tasks, users can specify them in the import wizard.
  • Shareable settings file: To have the same project setup across machines, the project import settings (saved in the project folders) can be shared between developers.
  • Partial import: In case of a large project clients can decide to import only a subset of modules from a multi-module build.
  • Binary dependency substitution: Multiple builds can be included in the same workspace, and if one build has a dependency matching to a module in the other build, then the jar dependency is replaced with a reference to the module.

Please note, that the Buildship team is working hard to implement all missing features.

Distinction between the plugin contributions

A common use-case for the migration is when Buildship and STS Gradle are both installed in Eclipse. Since both plugins provide similar UI contributions, it is hard to distinguish which one belongs to what plugin. Here is a short comparison:

Wizards

New project (File > New > Other...) Import project (File > Import > Other...)

Views selection dialog

Dialog (Window > Show View > Other...)

Task views

Buildship task view STS task view

Launch shortcut

Buildship test launch shortcut STS launch shortcut

Run configurations

Buildship (Toolbar > Run configurations dropdown > Run Configurations... > Gradle) STS (Toolbar > External Tools Configurations dropdown > External tools Configurations... > Gradle Build)

Context menu

Buildship project context menu STS project context menu

Migration process

Starting from version 1.0.9 Buildship provides an option to perform a clean project import via the import wizard. Buildship automatically detects if there are existing project descriptors in the project folders and prompts the user to keep or override them. Unless there are advanced setting stored in the Eclipse descriptors, you should choose to override the files. If you have to keep them, then some manual cleanup is needed.

Migration steps

  1. Install the latest Buildship release. Download locations and instructions are in the Buildship [user documentation] (https://github.com/eclipse/buildship/blob/master/docs/user/Installation.md).
  2. Note the root module location of the project you want to migrate.
  3. Delete the projects from the workspace without physically removing them from the file system.
  4. Open the Buildship import wizard and specify the root project location.
    • Optionally set the advanced options (Gradle version, JVM argument, etc.) and check the project import preview.
  5. Click Finish to execute the import.
  6. When prompted, choose Overwrite Eclipse descriptors to perform a clean import, or choose the Keep option to preserve the plugin configuration.
  7. Disable the hidden file filter in the Project/Package Explorer view.
  8. For all projects, delete the .settings/gradle folder (it contains configuration data from STS Gradle).
Project location in preferences Remove project from workspace Import wizard Keep project descriptors

If you kept the existing Eclipse project descriptors, then change the following files in all workspace projects:

  • .project file:
    • delete the STS Gradle nature definition: <nature>org.springsource.ide.eclipse.gradle.core.nature</nature>
  • .classpath file:
    • delete the Gradle classpath container if exists:
      <classpathentry exported="true" kind="con" path="org.springsource.ide.eclipse.gradle.classpathcontainer"/>
    • add the Gradle classpath container to all Java project:
      <classpathentry kind="con" path="org.eclipse.buildship.core.gradleclasspathcontainer"/>
Show hidden files in Package Explorer view Show hidden files in Project Explorer view

Uninstalling STS Gradle

If none of your projects use the STS Gradle integration anymore, then it is recommended to uninstall the STS plugin. Removing features from Eclipse is a bit hidden, but it can be done with with the following steps.

  • Open the Eclipse about page.
    • On Linux/Windows: Menu > Help > About Eclipse.
    • On Mac: Menu > Eclipse > About Eclipse.
  • Click the Installation Details button
  • On the Installed Software page select the Gradle IDE and click Uninstall.
  • Click Finish in the new dialog.
  • Restart Eclipse when asked.
About Eclipse menu entry About Eclipse dialog Installated software Uninstall software dialog Restart Eclipse
Clone this wiki locally