Migration guide from STS Gradle to Buildship

转载：https://github.com/eclipse/buildship/wiki/Migration-guide-from-STS-Gradle-to-Buildship

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

• Deep Gradle integration: Buildship has a highly optimized integration with Gradle through the best usage of the IDE-integration interface called the Tooling API. Besides, Buildship is one of the key drivers of the Tooling API development. -- 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. This always happens automatically, without any manual configuration.
• Project configuration: Buildship automatically updates the Eclipse project configuration when the user issues a refresh. This way the IDE project and the Gradle module configuration stays as close as possible.
• 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.
• Partial import: In case of a large project clients can decide to import only a subset of modulesfrom 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.
• Task-driven configuration: By disabling dependency management, projects can be configured through executing tasks and refreshing project metadata from the disk.
• Task quick launcher: The tasks can be revealed and executed from a quick launcher dialog which is accessible from the projects' context menu or with the ctrl+alt+shift+r shortcut.
• Annotation processing: The JDT annotation processor is configured when the spring-boot-configration-processor is present on a project's classpath. This helps the users when they work on spring-boot applications.

Some of the above listed features of STS will soon be available in Buildship.

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.
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 theKeep 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:org.springsource.ide.eclipse.gradle.core.nature
• .classpath file:
  
  • delete the Gradle classpath container if exists: 
    
  • add the Gradle classpath container to all Java project: 
    

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