Installation Guide
1Do you need to install Bloop?
Bloop is a JVM-based build server that applications such as IDEs (e.g. Metals) or build tools (e.g. seed) can depend on. Typically, these applications use the Bloop Launcher to run bloop in the background of your machine. This means, you might be already using Bloop without knowing it.
So, do you need to install Bloop if these applications are already depending on and running bloop in the background?
The answer is no. You should only install bloop as a package if you want to:
- Install and use the Bloop CLI to send build commands to the bloop server from the comfort of your terminal. This includes autocompletions. It is always handy to have the CLI installed in your machine!
- Install the bloop server for the first time in your machine because you're planning to use it to build it for something or play with it.
- Have complete control over which bloop server version you're using and how it runs in the background. For example, because you want to use a Systemd configuration to run bloop.
If any of the above are true, please proceed with this guide and jump to the next step. If none is true or you don't know if they are true or false, it is recommended you do not install Bloop directly in your machine.
The following page explains how to get Bloop installed in your machine and how you can export your current project build to Bloop.
2Pick your installation method
Universal Installation
Package Managers
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
- Java 8 or higher
- 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:
systemctl --user start bloop
: starts up the bloop server.systemctl --user stop bloop
: stops the bloop server.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
- Java 8 or higher
- 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:
cat /usr/local/var/log/bloop/bloop.out.log
: check the build server logs via stdout.cat /usr/local/var/log/bloop/bloop.err.log
: check the build server logs via stderr.brew services start bloop
: starts up the bloop server.brew services stop bloop
: stops the bloop server.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
- Java 8 or higher
- 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:
- PSReadLine, a plugin that improves the PowerShell experience and supports bash completions.
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.5
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
3Set up your build
This section explains you how to export your build to Bloop manually.
You can skip this section if:
You are using a build tool that has built-in support for Bloop and exports the build automatically every time there is a change.
You are using IDEs such as Metals or IntelliJ. These tools have automatic support for exporting the build to Bloop through their "Import Build" or "Import Project" actions. If you are using or planning these IDEs, import the build in your IDE and skip this section.
If you have your project build and want to try the CLI on it, click on the build tool you use and keep reading.
Build tools
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.2'
}
}
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:
foo
comes from the compile source set; and,foo-test
comes from the test source set and depends onfoo
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:
- You are running the command-line invocation in the root base directory (e.g.
/disk/foo
). - The gradle build export process completed successfully.
- 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:
bloop compile --help
: shows the help section for compile.bloop compile foo-test
: compiles foo'ssrc/main
andsrc/test
.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.1: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.1: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.1:bloopInstall
(...)
Generated '/disk/foo/.bloop/foo.json'.
Generated '/disk/foo/.bloop/foo-test.json'.
where:
foo
defines the main project; and,foo-test
defines the test project and depends onfoo
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:
- You are running the command-line invocation in the root base directory (e.g.
/disk/foo
). - The Maven build export process completed successfully.
- 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:
bloop compile --help
: shows the help section for compile.bloop compile foo-test
: compiles foo'ssrc/main
andsrc/test
.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.
Requirements
- Your mill version needs to be >=
0.4.0-2-4dbbce
.
Install the plugin
Install bloop in build.sc
by replacing $MILL_VERSION
in the following
command:
import $ivy.`com.lihaoyi::mill-contrib-bloop:$MILL_VERSION`
Export your build
The mill command mill mill.contrib.Bloop/install
exports your mill build to bloop.
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 mill.contrib.Bloop/install
(...)
info Generated '/disk/foo/.bloop/foo.json'.
info Generated '/disk/foo/.bloop/foo-test.json'.
where:
foo
comes from the compile source set; and,foo-test
comes from the test source set and depends onfoo
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
foo
foo-test
If the results of bloop projects
is empty, check that:
- You are running the command-line invocation in the root base directory (e.g.
/disk/foo
). - The mill build export process completed successfully.
- 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:
bloop compile --help
: shows the help section for compile.bloop compile foo-test
: compiles foo'ssrc/main
andsrc/test
.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 tool | Build export | Built-in Compile / Test / Run |
---|---|---|
sbt | ✅ | ✅ experimental |
Gradle | ✅ | |
Maven | ✅ | |
Mill | ✅ | |
Bazel | ❌ | |
Pants | 🚧 work-in-progress |
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
.
Version | Published | Resolver |
---|---|---|
2.0.5 | 23 Oct 2018 12:55 | -r sonatype:releases |
2.0.5-39-a004214a-SNAPSHOT | 05 Dec 2024 18:03 | -r sonatype:releases |
Install bloop by adding the following line to your project/plugins.sbt
:
addSbtPlugin("ch.epfl.scala" % "sbt-bloop" % "2.0.5")
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.5"
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:
foo
comes from theCompile
sbt configuration; and,foo-test
comes from theTest
sbt configuration and depends onfoo
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:
- You are running the command-line invocation in the root base directory (e.g.
/disk/foo
). - The sbt build export process completed successfully.
- 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:
bloop compile --help
: shows the help section for compile.bloop compile foo-test
: compiles foo'ssrc/main
andsrc/test
.bloop test foo-test -w
: runs foo tests repeatedly with file watching enabled.
4Use Bloop
This is it! You already have Bloop and the Bloop CLI installed in your machine. Now, it's time to write Scala code and be productive.
You can either use an IDE such as Metals or IntelliJ to write code or play with the CLI if you want to explore what CLI options are available.
If you need help, you can always come over our Discord channel.