Installation Guide

With yay (replace by your favorite AUR helper):

yay -S bloop

If you want to use the Systemd service, also install bloop-systemd:

yay -S bloop-systemd

Requirements

1. Java 8 or higher
2. Python 2 or 3 (installation script and CLI client are written in Python)

The installation script installs the build server and the bloop command-line application (CLI). The build server must be started before the command-line application is used.

Running the server in the background

The AUR package bloop-systemd installs a Systemd service in your user configuration to start up the Bloop server automatically when you log into your machine. This service spares you from the cumbersome process of starting the build server before using any build client, enable it with:

systemctl --user enable bloop

Command examples to manager the server:

1. systemctl --user start bloop: starts up the bloop server.
2. systemctl --user stop bloop: stops the bloop server.
3. systemctl --user restart bloop: restarts the bloop server, required after every upgrade.

To learn more about bloop server and managing the server lifecycle automatically, head to the Build Server Reference.

Command-line completions

The installation script automatically installs completions for bash, zsh and fish; reload your shell to get it working.

brew install scalacenter/bloop/bloop

Requirements

1. Java 8 or higher
2. Python 2 or 3 (installation script and CLI client are written in Python)

The installation script installs the build server and the bloop command-line application (CLI). The build server must be started before the command-line application is used.

Running the server in the background

The Homebrew formula installs a Mac OS property list (plist) to start up the Bloop server automatically when you log into your machine. The property list spares you from the cumbersome process of starting the build server before running any bloop CLI command.

Command examples:

1. cat /usr/local/var/log/bloop/bloop.out.log: check the build server logs via stdout.
2. cat /usr/local/var/log/bloop/bloop.err.log: check the build server logs via stderr.
3. brew services start bloop: starts up the bloop server.
4. brew services stop bloop: stops the bloop server.
5. brew services restart bloop: restarts the bloop server.

To learn more about bloop server and managing the server lifecycle automatically, head to the Build Server Reference.

Command-line completions

The installation script automatically installs completions for bash, zsh and fish.

To use them you need to set up your shell to source Homebrew-installed completions by following the Homebrew Shell Completion guide. If you've already set them up for previous Homebrew packages you can skip the guide.

Add the bloop bundle to scoop:

scoop bucket add bloop-stable https://github.com/scalacenter/scoop-bloop.git

Check that the bucket is correctly configured:

scoop bucket list
scoop search bloop
// You should see the bloop scoop package listed here

Then, install it with:

scoop install bloop

Requirements

1. Java 8 or higher
2. Python 2 or 3 (installation script and CLI client are written in Python)

The installation script installs the build server and the bloop command-line application (CLI). The build server must be started before the command-line application is used. Start it with:

bloop server

This process can take a while to run the first time is executed. When the nailgun logs show up, verify your installation by running the command-line application:

$ bloop about
bloop v1.1.1

Running on Scala v2.12.7 and Zinc v1.1.1
Maintained by the Scala Center (Martin Duhem, Jorge Vicente Cantero)

Running the server in the background

Bloop's build server is a long-running process designed to provide the fastest compilation possible to users. As such, users are responsible for managing its lifecycle and minimizing the amount of times it's restarted.

Bloop does not have a service file for Windows so you have to start and stop the bloop server manually. It is recommended to have the bloop server running in a long-lived terminal session.

If you want to improve this situation, check this ticket which proposes a solution to this problem that is compatible with Windows Services.

To learn more about bloop server and managing the server lifecycle automatically, head to the Build Server Reference.

Command-line completions

Bloop does not support PowerShell completions at the moment. However, it does support Bash/Zsh command-line completions which are installed by default in the bloop installation directory (under /etc).

There are several projects that allow you to use Bash style completions in your PowerShell:

1. PSReadLine, a plugin that improves the PowerShell experience and supports bash completions.
2. ps-bash-completions, a single PowerShell module to install bash completions.

Requirements

• Java 8 or higher
• Coursier >= 2.0.0-RC6-13

Installation options

Coursier installation instructions can be found at https://get-coursier.io/docs/cli-installation.

After successfully installing it you can run:

cs install bloop --only-prebuilt=true

Coursier will install bloop in its installation directory. When installing, you might get a log similar to this:

➜  ~ ➜  ~ cs install bloop
https://repo1.maven.org/maven2/io/get-coursier/apps/maven-metadata.xml
  100.0% [##########] 993 B (20.2 KiB / s)
https://repo1.maven.org/maven2/io/get-coursier/apps/maven-metadata.xml
  No new update since 2020-05-11 10:44:44
https://repo1.maven.org/maven2/io/get-coursier/apps/0.0.23/apps-0.0.23.pom
  100.0% [##########] 1.3 KiB (12.9 KiB / s)
https://repo1.maven.org/maven2/org/scala-lang/scala-library/maven-metadata.xml
  No new update since 2020-04-23 06:26:04
Wrote bloop
Warning: /Users/jvicentecantero/Library/Application Support/Coursier/bin is not in your PATH
To fix that, add the following line to ~/.zshrc

Make sure you add the Coursier binary directory to your $PATH.

The installation script installs the build server and the bloop command-line application (CLI). The build server must be started before the command-line application is used. Start it with:

bloop server

Note that bloop server is a command-line alias for $BLOOP_INSTALLATION_DIR/blp-server. If the server is not located in the same directory as the bloop CLI binary, pass in the server location to the `--server-location` flag.

Then, verify your installation by running the command-line application:

$ bloop about
bloop v2.0.18

Running on Scala v2.12.7 and Zinc v1.1.0
Maintained by the Scala Center (Martin Duhem, Jorge Vicente Cantero)

Running the server in the background

Bloop's build server is a long-running process designed to provide the fastest compilation possible to users. As such, users are responsible for managing its lifecycle and minimizing the amount of times it's restarted.

We have seen how to manually start the server with bloop server. However, you may prefer an automatic solution that starts the server in the background when you log in and allows you to quickly restart it. There are several mechanisms to do so, read the Build Server Reference.

Command-Line Completions

Bloop supports command-line completions in bash, zsh and fish. The use of command-line autocompletions is recommended as it significantly improves the user experience. The installation of autocompletions via curl requires you to configure the completions manually.

Note that the following instructions assume that the bloop installation directory is the default $HOME/.bloop.

Zsh Completions

Add the following to your ~/.zshrc:

autoload -U compinit
fpath=($HOME/.bloop/zsh $fpath)
compinit

Bash Completions

Add the following to your ~/.bash_profile:

. $HOME/.bloop/bash/bloop

Fish Completions

Symlink the fish completions file in the Bloop installation directory to your local fish completions directory (usually ~/.config/fish/completions).

ln -s $HOME/.bloop/fish/bloop.fish ~/.config/fish/completions/bloop.fish

Make sure that the target fish completions directory already exists.

Bloop CLI completions will not work if the build server is not running when the shell is reloaded. Make sure that, before reloading the fish shell, the build server is started.

If you still experience problems, reload the completion script:

source $HOME/.bloop/fish/bloop.fish bloop.fish

Or, if you use Oh My Fish:

omf reload

Requirements

• For Scala 2: at least Gradle v5.0
• For Scala 3: at least Gradle v7.3
• For Android: at least Gradle v6.1.1
• Latest (tested) supported version is v7.5

Install the plugin

Add bloop to your build.gradle with:

buildscript {
  repositories {
    // Add here whatever repositories you're already using
    mavenCentral()
  }

  dependencies {
    classpath 'ch.epfl.scala:gradle-bloop_2.12:1.6.4'
  }
}

Then, enable bloop in all your Gradle projects with:

allprojects {
  // test is for compatibility with Metals import
  if (!plugins.hasPlugin("bloop")) {
    apply plugin: "bloop"
  }
}

For a more advanced configuration, read the Plugin Configuration below.

Export your build

The gradle command bloopInstall exports your gradle build to bloop.

The gradle plugin generates a configuration file per every source set in your build definition. By default, there are two source sets: that of compile and that of test. Bloop will skip config file generation for those projects that are not either Java or Scala.

$ ./gradlew bloopInstall

For example, a build with a single Scala project foo generates two configuration files by default:

$ ./gradlew bloopInstall
(...)
Generated '/disk/foo/.bloop/foo.json'.
Generated '/disk/foo/.bloop/foo-test.json'.

where:

1. foo comes from the compile source set; and,
2. foo-test comes from the test source set and depends on foo

If you have applied Bloop to all the projects in your build but some of your projects can't be understood by Bloop (for example, they are not Java or Scala projects), you will see the following log:

Ignoring 'bloopInstall' on non-Scala and non-Java project '$NON_JVM_PROJECT'

You can safely ignore such messsages.

Verify installation and export

Remember that the build server must be running in the background, as suggested by the Setup page.

Verify your installation by running bloop projects in the root of the gradle workspace directory.

$ bloop projects
foo
foo-test

If the results of bloop projects is empty, check that:

1. You are running the command-line invocation in the root base directory (e.g. /disk/foo).
2. The gradle build export process completed successfully.
3. The .bloop/ configuration directory contains bloop configuration files.

Debug the export with ./gradlew bloopInstall -Si.

If you suspect bloop is loading the configuration files from somewhere else, run --verbose:

$ bloop projects --verbose
[D] Projects loaded from '/my-project/.bloop':
foo
foo-test

Here's a list of bloop commands you can run next to start playing with bloop:

1. bloop compile --help: shows the help section for compile.
2. bloop compile foo-test: compiles foo's src/main and src/test.
3. bloop test foo-test -w: runs foo tests repeatedly with file watching enabled.

Requirements

• Your build uses scala-maven-plugin

Export your build

The Bloop plugin for Maven doesn't need to be installed, you can run bloopInstall, the task to export your Maven builds to bloop, with the following command.

$ mvn ch.epfl.scala:bloop-maven-plugin:2.0.3:bloopInstall

In some cases, when you are using generated sources in you project you might need to run:

$ mvn generate-sources ch.epfl.scala:bloop-maven-plugin:2.0.3:bloopInstall

Note: if you've used this command before you'll have noticed the artifact name has changed. In the past you would have used maven-bloop_2.13, however as of the 2.x series the artifact name has changed to bloop-maven-plugin.

To build with a single Scala project foo generates two configuration files:

$ mvn ch.epfl.scala:bloop-maven-plugin:2.0.3:bloopInstall
(...)
Generated '/disk/foo/.bloop/foo.json'.
Generated '/disk/foo/.bloop/foo-test.json'.

where:

1. foo defines the main project; and,
2. foo-test defines the test project and depends on foo

The bloop-maven-plugin generates two configuration files per Maven project. One project for the main sources and another one for the tests. Bloop will skip config file generation for those projects that are not either Java or Scala.

Verify installation and export

Verify your installation by running bloop projects in the root of the Maven workspace directory.

$ bloop projects
foo
foo-test

If the results of bloop projects is empty, check that:

1. You are running the command-line invocation in the root base directory (e.g. /disk/foo).
2. The Maven build export process completed successfully.
3. The .bloop/ configuration directory contains bloop configuration files.

If you suspect bloop is loading the configuration files from somewhere else, run --verbose:

$ bloop projects --verbose
[D] Projects loaded from '/my-project/.bloop':
foo
foo-test

Here's a list of bloop commands you can run next to start playing with bloop:

1. bloop compile --help: shows the help section for compile.
2. bloop compile foo-test: compiles foo's src/main and src/test.
3. bloop test foo-test -w: runs foo tests repeatedly with file watching enabled.

After verifying the export, you can continue using Bloop's command-line application or any build client integrating with Bloop, such as Metals.

Export your build

The following mill command automatically downloads the required plugin and exports your mill build to bloop:

mill --import ivy:com.lihaoyi::mill-contrib-bloop: mill.contrib.bloop.Bloop/install

The mill plugin generates a configuration file per every compile and test sources in your build definition. For example, a build with a single Scala project foo generates two configuration files by default:

$ mill --import ivy:com.lihaoyi::mill-contrib-bloop: mill.contrib.bloop.Bloop/install
(...)
[120/123] MillBuildRootModule.bloop.writeConfigFile
[120] Wrote /disk/foo/.bloop/mill-build-.json
[121/123] foo.bloop.writeConfigFile
[121] Wrote /disk/foo/.bloop/foo.json
[122/123] foo.test.bloop.writeConfigFile
[122] Wrote /disk/foo/.bloop/foo.test.json
[123/123] =================== mill.contrib.bloop.Bloop/install =================== 10s

where:

1. foo comes from the compile source set; and,
2. foo.test comes from the test source set and depends on foo

Verify installation and export

If you haven't installed bloop and its CLI yet, follow these instructions before proceeding.

Verify your installation by running bloop projects in the root of the mill workspace directory.

$ bloop projects
mill-build-
foo
foo.test

If the results of bloop projects is empty, check that:

1. You are running the command-line invocation in the root base directory (e.g. /disk/foo).
2. The mill build export process completed successfully.
3. The .bloop/ configuration directory contains bloop configuration files.

If you suspect bloop is loading the configuration files from somewhere else, run --verbose:

$ bloop projects --verbose
[D] Projects loaded from '/my-project/.bloop':
mill-build-
foo
foo.test

Here's a list of bloop commands you can run next to start playing with bloop:

1. bloop compile --help: shows the help section for compile.
2. bloop compile foo.test: compiles foo's src/main and src/test.
3. bloop test foo.test -w: runs foo tests repeatedly with file watching enabled.

After verifying the export, you can continue using Bloop's command-line application or any build client integrating with Bloop, such as Metals.

id: overview title: Overview sidebar_label: Overview

Bloop supports several build tools with varying degree of functionality.

Build Export

The most basic integration is Build Export. Build export is a task in your build tool that translates your build definitions to Bloop configuration files, which are used by Bloop to compile, test and run your Scala code. It provides all you need to get started with Bloop.

Exporting your build is supported by a large array of popular Scala and Java build tools. However, it's a tedious process that users must remember to run whenever their build changes (client integrations such as Metals can export the build automatically, but that's usually not the case if you're interfacing directly with the bloop CLI).

Built-in compile, test and run

Built-in compile, test and run is a richer build tool integration that swaps your build tool's implementation of compile, test and run by their implementation in Bloop. This integration relieves users from exporting the build (build export is automatic) and instead provides a transparent build tool integration users are unaware of.

Whereas built-in integrations are not fully developed yet, a built-in build tool integration for sbt is planned for the next release. These integrations will help users benefit from the speed and reliability of a more modern Scala toolchain with minimum interference in their current workflow.

Install the plugin

Here is a list of the latest Bloop stable and development versions for sbt-bloop.

Install bloop by adding the following line to your project/plugins.sbt:

addSbtPlugin("ch.epfl.scala" % "sbt-bloop" % "2.0.18")

If this does not work due to using an internal Artifactory, use instead:

libraryDependencies += "ch.epfl.scala" % "sbt-bloop_2.12_1.0" % "2.0.18"

After that, start up sbt or reload your sbt shell to load the plugin.

Export your build

The sbt command bloopInstall exports your sbt build to bloop.

In bloop, an sbt project is represented as a pair of (sbt project, sbt configuration) and it's written to a configuration directory. The default location of this directory in your workspace is .bloop/ (you may want to add .bloop/ to your .gitignore file).

For example, a build with a single project foo generates two configuration files by default (one per Compile and Test configuration):

$ sbt bloopInstall
[info] Loading global plugins from /Users/John/.sbt/1.0/plugins
(...)
[success] Generated '/disk/foo/.bloop/foo.json'.
[success] Generated '/disk/foo/.bloop/foo-test.json'.

where:

1. foo comes from the Compile sbt configuration; and,
2. foo-test comes from the Test sbt configuration and depends on foo

If a build enables the IntegrationTest configuration in a project, Bloop will also export it.

Any change in the build affecting the semantics of a project (such as adding a new library dependency, a resource or changing the project name) requires the user to run bloopInstall. When a project is removed in the build, bloopInstall will automatically remove its old configuration from the .bloop directory.

Verify installation and export

Verify your installation by running bloop projects in the root of the sbt workspace directory.

$ bloop projects
foo
foo-test

If the results of bloop projects is empty, check that:

1. You are running the command-line invocation in the root base directory (e.g. /disk/foo).
2. The sbt build export process completed successfully.
3. The .bloop/ configuration directory contains bloop configuration files.

If you suspect bloop is loading the configuration files from somewhere else, use --verbose:

$ bloop projects --verbose
[D] Projects loaded from '/my-project/.bloop':
foo
foo-test

Here's a list of bloop commands you can run next to start playing with bloop:

1. bloop compile --help: shows the help section for compile.
2. bloop compile foo-test: compiles foo's src/main and src/test.
3. bloop test foo-test -w: runs foo tests repeatedly with file watching enabled.