Skip to content

Using sbteclipse

Jump to bottom
Jean-Luc Deprez edited this page Nov 18, 2022 · 2 revisions

Using sbteclipse

Please make sure that you have installed sbteclipse like described here.

sbteclipse provides the command eclipse that will create Eclipse project definitions for your sbt build. This command can be configured via sbt settings. Some configuration parameters can even be given via options. As there are sensible defaults for all settings, you don't necessarily have to apply any custom configuration. Just execute the command eclipse in an sbt session:

> eclipse
[info] About to create Eclipse project files for your project(s).
[info] Updating {file:/Users/heiko/tmp/test/}test...
...
[info] Successfully created Eclipse project files for project(s): test

If you see the message "Successfully created Eclipse project files ..." you will find one or more Eclipse project definitions in your project directory. An Eclipse project definition consists of a .project file, a .classpath file and optionally files in the .settings/ folder. If you have a simple project, you will find one Eclipse project definition in the root directory of your project. But if you have a multi-module build, parent projects are skipped by default and Eclipse project definitions will only be created for the "bottom projects".

In order to import these projects into Eclipse, please open a workspace which should be different from the sbt project directory. Then use the Import Wizard to import Existing Projects into Workspace.

Settings

The following settings, or more precisely setting keys, are defined in the singleton object EclipseKeys which is a member of the com.typesafe.sbteclipse.plugin.EclipsePlugin plugin. This follows the plugins best practices in order to avoid name clashes between various plugins.

In .sbt build definitions (build.sbt files) all plugin members are automaically wild-card imported which means you can use EclipseKeys without an import clause. If you are using .scala build definitions (Build.scala files), you have to import com.typesafe.sbteclipse.plugin.EclipsePlugin.EclipseKeys.

In both cases, you have to either prefix the below setting keys with EclipseKeys, e.g. EclipseKeys.withSource, or you have to import the setting keys, e.g. via a wildcard import clause.

createSrc

This setting of type EclipseCreateSrc.ValueSet determines the source kinds to be included. The available kinds are the Value members of the EclipseCreateSrc enumeration: ManagedSrc, ManagedResources and ManagedClasses. It defaults to EclipseCreateSrc.Default, which comprises ManagedSrc and ManagedResources.

The following example shows how to add the resources folders:

EclipseKeys.createSrc := EclipseCreateSrc.Default + EclipseCreateSrc.ManagedClasses

eclipseOutput

This setting of type Option[String], which defaults to None, lets you control whether sbteclipse should use the same target directories for sbt and Eclipse. If Some(name), sbteclipse will use the given name for the Eclipse output directory.

The following example shows how to make sbteclipse use the given name for the Eclipse output directory:

EclipseKeys.eclipseOutput := Some(".target")

executionEnvironment

This setting of type Option[EclipseExecutionEnvironment.Value], which defaults to None, can be used to specify an optional Eclipse execution environment. The available values are the Value members of the EclipseExecutionEnvironment enumeration: JavaSE17, JavaSE16, J2SE15, J2SE14, J2SE13, J2SE12 and JRE11.

The following example shows how to use the execution environment for Java 6:

EclipseKeys.executionEnvironment := Some(EclipseExecutionEnvironment.JavaSE16)

jdtMode

This setting of type EclipseJDTMode.Value, which defaults to Ignore, can be used to control the writing mode of the .settings/org.eclipse.jdt.core.prefs file, e.g. to configure Java language compatibility for Red Hat Java LSP. The prefs values are derived from the executionEnvironment. The available values are the Value members of the EclipseJDTMode enumeration: Ignore, Remove, Update and Overwrite.

The following example shows how to force a clean write of the prefs file:

EclipseKeys.jdtMode := EclipseJDTMode.Overwrite

projectFlavor

This setting of type EclipseProjectFlavor.Value, which defaults to Scala, is used to specify which builder and natures Eclipse should use. The available values are the Value members of the EclipseProjectFlavor enumeration: Scala, Java.

The following example shows how to set the project flavor to Java:

EclipseKeys.projectFlavor := EclipseProjectFlavor.Java

skipParents

This setting of type Boolean, which defaults to true, tells sbteclipse whether creating Eclipse project definitions should be skipped for parent projects. If your parent projects are merely folders aggregating sub projects, then using true will ease importing all your sub projects into Eclipse using the Import Wizard like described above by reducing the number of necessary "runs".

Attention: This is a build level setting, not a project level one!

The following example shows how to not skip creating Eclipse project definitions for parent projects:

EclipseKeys.skipParents in ThisBuild := false

skipProject

This setting of type Boolean, which defaults to false, tells sbteclipse whether creating Eclipse project definitions should be skipped for an individual project.

The following example shows how to skip creating Eclipse project definitions for a given project:

EclipseKeys.skipProject := true

relativizeLibs

This setting of type Boolean, which defaults to true, lets you control whether sbteclipse should try to use relative paths for the library dependencies. Of course this only applies to managed dependencies when using retrieveManaged := true as well as to unmanaged libraries.

The following example shows how to make sbteclipse not use relative paths:

EclipseKeys.relativizeLibs := false

useProjectId

This setting of type Boolean, which defaults to false, tells sbteclipse whether it should use the project id instead of the project name for the name of the Eclipse project.

The following example shows how to use the project id:

EclipseKeys.useProjectId := true

withSource

This setting of type Boolean, which defaults to false, lets you control whether sbteclipse should try to download source artifacts and create Eclipse source attachments for library dependencies.

The following example shows how to make sbteclipse create source attachments:

EclipseKeys.withSource := true

withJavadoc ++++++++++

This setting of type Boolean, which defaults to false, lets you control whether sbteclipse should try to download JavaDoc artifacts and create Eclipse JavaDoc attachments for library dependencies.

The following example shows how to make sbteclipse create JavaDoc attachments:

EclipseKeys.withJavadoc := true

withBundledScalaContainers ++++++++++

This setting of type Boolean, which defaults to true, lets you control whether sbteclipse replaces mentions of the scala compiler and library on classpath with a version-less placeholder (referring to whichever scala version the Eclipse ScalaIDE plugin currently runs on).

The following example shows how to make sbteclipse not remove version information from the scala compiler & library :

EclipseKeys.withBundledScalaContainers := false

Advanced settings

Attention: The following settings are for advanced users only. Please make sure you know what you are doing!

classpathTransformerFactories

This setting of type SettingKey[Seq[EclipseTransformerFactory[RewriteRule]]] creates factories for a rewrite rule for the .classpath file.

configurations

This setting of type Set[Configuration] lets you control the configurations to take into account. It defaults to Set(Compile, Test).

preTasks

This setting of type Seq[TaskKey[_]] lists the tasks to be evaluated prior to creating the Eclipse project definition. It defaults to empty sequence.

projectTransformerFactories

This setting of type SettingKey[Seq[EclipseTransformerFactory[RewriteRule]]] creates factories for a rewrite rule for the .project file.

classpathEntryTransformerFactory

Deprecated: Use classpathTransformerFactories instead!

This setting of type SettingKey[EclipseClasspathEntryTransformerFactory] creates a transformer for classpath entries. The default replaces scala-library.jar with the Scala container, scala-compiler.jar with the Scala compiler container and passes all others unchanged.

Options

Some settings are quite unlikely to ever change for a particular build, but others might need to be changed frequently, e.g. the Eclipse execution environment. Of course you could just change the setting temporarily within the sbt session instead of changing these in your build definition. But for most of the above listed (not advanced) settings sbteclipse offers an even quicker way: options. These can be given after the command and thanks to sbt you have auto-completion available. The following examples show the available options and how to use these:

> eclipse execution-environment=J2SE-1.6
> eclipse skip-parents=false
> eclipse with-source=true
> eclipse jdt-mode=Remove

Eclipse support for build definition

If you want to get Eclipse support for the sbt build definition, e.g. for your Build.scala file, follow these steps:

  • If you are not using sbteclipse as as global plugin, which is the recommended way, but as a local plugin for your project, you first have to add sbteclipse as a plugin (addSbtPlugin(...)) to the build definition project, i.e. to project/project/plugins.sbt
  • In the sbt session, execute reload plugins
  • Set the name of the build definition project to something meaningful: set name := "sbt-build"
  • Execute eclipse and then reload return
  • Import the build definition project into Eclipse and add the root directory to the build path
Clone this wiki locally