JSON Configuration Reference
A bloop configuration file:
- Is a JSON object, usually stored in a JSON file below
$WORKSPACE/.bloop/
- Defines a single Bloop project, its build inputs and its build outputs
- Has a well-specified format evolved in a binary compatible way
- Contains machine-dependent data such as user paths (cannot be shared across machines)
To use bloop you first need to generate Bloop configuration files from your build tool. Next is an example of the simplest bloop configuration file possible.
{
"version" : "1.0.0",
"project" : {
"name" : "foo",
"directory" : "/disk/foo",
"sources" : ["/disk/foo/src/main/scala"],
"dependencies" : [],
"classpath" : ["/disk/foo/library/scala-library.jar"],
"out" : "/disk/foo/target",
"classesDir" : "/disk/foo/target/classes"
}
}
Evolution and compatibility guarantees
The data in a bloop configuration file powers the build server functionality so it is common that with the release of new bloop versions more fields are added to the configuration file format.
However, to avoid breaking any existing clients, changes in the Bloop configuration file are done
such that backwards compatibility is always guaranteed. For example, a 1.1.0
Bloop release will
understand data stored in a 1.0.0
configuration file.
JSON Schema
The configuration file has a clear specification in the following JSON schema. The JSON schema file specifies the type of every field, its description and content examples for every field.
If you find yourself editing bloop configuration files by hand, you can also use the JSON schema to provide autocompletions and simple type error detection.
Generating configuration files
Install the bloop-config
dependency in your build:
sbt
libraryDependencies += "ch.epfl.scala" %% "bloop-config" % "1.5.5"
mill
def ivyDeps = Agg(ivy"ch.epfl.scala::bloop-config:1.5.5")
bloop-config
is published for 2.11-2.13 on the JVM and JS. It implements
encoders and decoders to read and write configuration files. Once the library is
added in your build:
- Create an instance of
bloop.config.Config.File
and populate all its fields. - Write the json file to a
target
path withbloop.config.Config.File.write(config, target)
.