The build server is at the core of bloop. It runs in the background and is the responsible for scheduling and running client actions.
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.
Start the build server
At the end of the day, the build server is an artifact in Maven Central. However,
the recommended way of starting the server is via the
bloop server invocation.
bloop server is an OS-independent way of starting the server that abstracts over
some of the messy details of running a JVM application with the right configuration.
- Finds the location of a bootstrapped jar automatically in the bloop installation directory
- Runs the server with the jvm options in the
.jvmoptsfile in the bloop installation directory. The
.jvmoptsfile can contain the flags separated by either a new line or a whitespace.
- Provides a way to evolve the way the server is run and managed in the future, which makes it especially compatibility-friendly.
The bloop installation directory is the directory where
bloop is located. In Unix-based
systems, the bloop installation directory can be found by running
If you are integrating your tool with bloop and want to install and start the server automatically in the background, you can use Bloop's built-in Launcher.
bloop [FLAGS...] server [JVM_OPTS...] NAILGUN_PORT
NAILGUN_PORTmust be a free TCP port. For now, only ports in the localhost is supported.
JVM_OPTSmust be valid JVM arguments prefixed with
-J, used to pass in temporary jvm options to the server. For a permanent solution, add the options in
Use the server jar or script in the given path
Automatic management of the server
It is generally a good practice to have a way to manage the lifecycle of the server. Depending on your operating system, there exist several solutions that allow you to start, stop, restart and inspect the status of the build server at any time.
Bloop supports the following mechanisms out-of-the-box:
brew servicesin OSX systems
systemdin Linux systems
- Desktop Entries in systems that follow the XDG Desktop Entry Specification
Windows users do not have a way of starting the server via Windows Services, so the lifecycle management has to be manual. Do you want to help improve the situation? Check this ticket.
Brew services are powered by
launchd and need a macOS property list (
plist) that explains how to
start the Bloop server and under which conditions. The property list is installed by default in the
Homebrew installation and doesn't require any extra steps to use it.
cat /usr/local/Cellar/bloop/$version/log/bloop/bloop.out.log: check the build server logs via stdout.
cat /usr/local/Cellar/bloop/$version/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 have the Bloop server be automatically managed by systemd, install Bloop's systemd service:
$ systemctl --user enable $HOME/.bloop/systemd/bloop.service $ systemctl --user daemon-reload
The build server will be started whenever you log in your computer and killed whenever your session is closed.
It is also possible to only kill the build server when the machine is shut down. Please refer to Systemd's documentation about user services for advanced configuration.
journalctl --user-unit bloop: check the build server logs.
systemctl --user status bloop: checks the status of the build server.
systemctl --user start bloop: starts up the bloop server.
systemctl --user stop bloop: stops the bloop server.
systemctl --user restart bloop: restarts the build server.
via Desktop Entries
A desktop entry is a
bloop.desktop file which your desktop environment recognizes as a launcher if
it supports the freedesktop.org Desktop Entry
For example, Ubuntu recognizes and displays desktop entries in the application menu next to an icon.
Install a desktop entry with:
$ mkdir -p $HOME/.local/share/applications $ ln -s $HOME/.bloop/xdg/bloop.desktop $HOME/.local/share/applications/
If you want to start the server automatically, add the desktop entry to
$ mkdir -p $HOME/.config/autostart $ ln -s $HOME/.bloop/xdg/bloop.desktop $HOME/.config/autostart/
Ignore exceptions in server logs
Bloop uses Nailgun, which sometimes prints exceptions in your server logs such as:
Unable to load nailgun-version.properties. NGServer [UNKNOWN] started on address localhost/127.0.0.1 port 8212. [W] Internal error in session java.io.EOFException at java.base/java.io.DataInputStream.readInt(DataInputStream.java:397) at com.martiansoftware.nailgun.NGCommunicator.readCommandContext(NGCommunicator.java:140) at com.martiansoftware.nailgun.NGSession.run(NGSession.java:197)
You can safely ignore these warnings and exceptions.