diff --git a/docs-gen/src/main/scala/bloop/docs/ReleasesModifier.scala b/docs-gen/src/main/scala/bloop/docs/ReleasesModifier.scala index f103828b1a..6094ae215e 100644 --- a/docs-gen/src/main/scala/bloop/docs/ReleasesModifier.scala +++ b/docs-gen/src/main/scala/bloop/docs/ReleasesModifier.scala @@ -32,7 +32,7 @@ class ReleasesModifier extends StringModifier { } class LauncherReleasesModifier extends StringModifier { - override val name: String = "launcher-releases" + override val name: String = "rifle-releases" override def process(info: String, code: Input, reporter: Reporter): String = { val xml = { try { @@ -44,8 +44,8 @@ class LauncherReleasesModifier extends StringModifier { - {Sonatype.releaseLauncher.version} - {Sonatype.releaseLauncher.date} + {Sonatype.releaseRifle.version} + {Sonatype.releaseRifle.date} -r sonatype:releases diff --git a/docs-gen/src/main/scala/bloop/docs/Sonatype.scala b/docs-gen/src/main/scala/bloop/docs/Sonatype.scala index 88e881d736..b272de7601 100644 --- a/docs-gen/src/main/scala/bloop/docs/Sonatype.scala +++ b/docs-gen/src/main/scala/bloop/docs/Sonatype.scala @@ -22,7 +22,7 @@ case class Release(version: String, lastModified: Date) { object Sonatype { lazy val releaseBloop = fetchLatest("bloop-frontend_2.12") lazy val releaseBloopMaven = fetchLatest("bloop-maven-plugin") - lazy val releaseLauncher = fetchLatest("bloop-launcher_2.12") + lazy val releaseRifle = fetchLatest("bloop-rifle_2.13") lazy val releaseBloopGradle = fetchLatest("gradle-bloop_2.13") /** Returns the latest published snapshot release, or the current release if. */ diff --git a/docs/build-tools/gradle.md b/docs/build-tools/gradle.md index f950f4c24a..37806fc794 100644 --- a/docs/build-tools/gradle.md +++ b/docs/build-tools/gradle.md @@ -28,12 +28,6 @@ Learn how to get set up by following the instructions below. ## Install the plugin -Here is a list of the latest Bloop stable and development versions. - -```scala mdoc:releases -I am going to be replaced by the docs infrastructure. -``` - Add bloop to your `build.gradle` with: ```gradle diff --git a/docs/contributing-guide.md b/docs/contributing-guide.md index 0d20fb1af9..807ce423c3 100644 --- a/docs/contributing-guide.md +++ b/docs/contributing-guide.md @@ -48,10 +48,8 @@ tooling infrastructure. 1. `buildpress` is an application that given a list of `(project-name, vcs-uri)` will export a build to bloop. 1. `docs` and `docs-gen` define our docs infrastructure. 1. `benchmark-bridge` and `benchmarks` define our compiler benchmark infrastructure. -1. `launcher` is an application to spawn a bloop server and establish a +1. `bloop-rifle` is a module to start a bloop server and establish a bsp/cli connection to it. -1. `nailgun` is a git submodule of `scalacenter/nailgun`, a fork of `facebook/nailgun`. -1. `sockets` is a library to use Unix Domain sockets and Named Pipes in Windows. 1. `website` contains the [Docusaurus](https://docusaurus.io/) code of our website. ## Set the repository up @@ -111,7 +109,7 @@ them to your project. For example, to depend on the latest SNAPSHOT of bloop launcher in sbt, add the following to your project: ```scala -libraryDependencies += "ch.epfl.scala" % "bloop-launcher" % "$VERSION" +libraryDependencies += "ch.epfl.scala" % "bloop-rifle" % "$VERSION" ``` ### Install a SNAPSHOT release in your machine @@ -184,11 +182,13 @@ local installation by comparing the SNAPSHOT version you wanted to install with the version of the running server. ```bash -➜ bloop about -bloop v1.2.5+264-3441652d +➜ bloop v2.0.0 + +Using Scala v2.12.19 and Zinc v1.10.1 +Running on Java JDK v21 (/usr/lib/jvm/openjdk21) + -> Supports debugging user code, Java Debug Interface (JDI) is available. +Maintained by the Scala Center and the community. -Running on Scala v2.12.8 and Zinc v1.2.1+110-85b9a03c -Maintained by the Scala Center (Martin Duhem, Jorge Vicente Cantero) ``` Note the bloop version number in the first line of the above logs. diff --git a/docs/guide/first-step.md b/docs/guide/first-step.md index f611cc1769..dee25aef45 100644 --- a/docs/guide/first-step.md +++ b/docs/guide/first-step.md @@ -1,7 +1,7 @@ Bloop is a JVM-based build server that applications such as IDEs (e.g. [Metals](https://scalameta.org/metals)) or build tools (e.g. [seed](https://github.com/tindzk/seed)) can depend on. Typically, these -applications use the [Bloop Launcher](docs/launcher-reference) to run bloop +applications use the [Bloop Launcher](docs/bloop-rifle) to run bloop in the background of your machine. This means, you might be already using Bloop without knowing it. diff --git a/docs/launcher.md b/docs/launcher.md deleted file mode 100644 index 4016747426..0000000000 --- a/docs/launcher.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -id: launcher-reference -title: Launcher Reference -sidebar_label: Built-in Launcher ---- - -The launcher is a lightweight artifact (~122K) that installs and configures -bloop. The goal of the launcher is to relieve clients of the burden of -installing and managing the lifetime of background build servers. - -The launcher implements the [Build Server Discovery protocol][server-discovery] -which allows clients to establish a bsp connection and communicate with the -server via stdin and stdout. - -## `launcher` - -#### Usage - -**Synopsis**: `launcher [JVM_OPTS...] [FLAGS...] BLOOP_VERSION` - -* `BLOOP_VERSION` must be a bloop version >= 1.2.0. This version is only - used in case an installation is tried. - > There is no guarantee that the server provided to the client will be of this version. -* `JVM_OPTS` must be valid JVM arguments prefixed with `-J`. - -#### Flags - -
-
--skip-bsp-connection (type: bool)
-

Do not attempt a bsp connection, but exit as soon as bloop has been installed and a server is running in the background.

-
- -## Description - -The high-level logic steps of the launcher can be summarized as follows: - -1. If bloop is not detected in the `$PATH` or `$HOME/.bloop/`, install it. - * If the universal installation (that requires `curl` and `python`) fails, - then we attempt to resolve bloop and launch an embedded server with - a concrete bsp command. This operation is only attempted if and only if - `--skip-bsp-connection` is not used. -1. Run a server in the background if it's absent. -1. When a server is running: - * If `--skip-bsp-connection`: return - * Else establish a bsp connection with the server and forward any message - from the launcher stdin to the server and from the server to the launcher - stdout. - -### Reuse server in the background - -The launcher will always try to reuse a server already running or spawned by -previous launcher executions to ensure that build servers are as hot and -efficient as possible. - -### Use the launcher when off-line - -The launcher is designed to be off-line friendly, e.g. if after running the -launcher there is no internet connection, the launcher will not need to hit -internet again and will instead populate data from caches. The launcher will -fail fatally in off-line scenarios if and only if the server is not installed -from the start. - -## Usage - -### Run the launcher manually - -Clients can depend on the launcher and run it when they see fit. The flag -`--skip-bsp-connection` is particularly useful for clients wishing to install -and spawn a bloop version, but that do not wish to use BSP and instead prefer -to detect manually the installed `bloop` version by the launcher and [run the -CLI](cli/reference). - -#### Install the launcher - -```scala mdoc:launcher-releases -I am going to be replaced by the docs infrastructure. -``` - -The launcher is independent from bloop but it's released with the same cadence than the bloop build server. Therefore, you can expect a build server version to have an accompanying launcher version. - -### Open a BSP connection - -To open a bsp a bsp connection with Bloop's build server you need -to follow the [Build Server Discovery protocol][server-discovery]. BSP allow -clients to connect to a BSP server in a build-tool-independent way through BSP -connection files, a JSON file with build server metadata and an `argv` field -that, if shelled out, will establish a bsp connection with a server. - -The bloop BSP connection file is created automatically by any of the supported -bloop installation methods (in the global `.bsp` directory) or by any of its -build plugins (in the `.bsp` workspace directory). If you do not depend on -a build plugin or require the installation of bloop, you are required to create -a bloop BSP connection file to allow you and other servers follow the Build -Server Protocol. - -[server-discovery]: https://github.com/scalacenter/bsp/blob/v2.0.0-M2/docs/bsp.md#bsp-connection-protocol diff --git a/docs/rifle.md b/docs/rifle.md new file mode 100644 index 0000000000..b760587fa8 --- /dev/null +++ b/docs/rifle.md @@ -0,0 +1,96 @@ +--- +id: bloop-rifle +title: Launcher Reference +sidebar_label: Built-in Launcher +--- + +Bloop rifle is a lightweight artifact that installs and configures bloop. The +goal of Bloop rifle is to relieve clients of the burden of installing and +managing the lifetime of background build servers. + +Bloop rifle implements the [Build Server Discovery protocol][server-discovery] +which allows clients to establish a BSP connection and communicate with the +server via stdin and stdout. + +For an example of using Bloop rifle, see the +[Bloop CLI module](https://github.com/scalacenter/bloop/tree/main/cli) and +[Metals](https://github.com/scalameta/metals/blob/main/metals/src/main/scala/scala/meta/internal/metals/BloopServers.scala) + +## Description + +Using Bloop rifle directly is more complex than using the CLI. + +1. Clients that want to start Bloop need to use `BloopRifleConfig`, which has some + default values, but it needs a way to download Bloop binaries provided via + classpath options. + +```scala +final case class BloopRifleConfig( + address: BloopRifleConfig.Address, + javaPath: String, + javaOpts: Seq[String], + classPath: String => Either[Throwable, Seq[File]], + workingDir: File, + bspSocketOrPort: Option[() => BspConnectionAddress], + bspStdin: Option[InputStream], + bspStdout: Option[OutputStream], + bspStderr: Option[OutputStream], + period: FiniteDuration, + timeout: FiniteDuration, + startCheckPeriod: FiniteDuration, + startCheckTimeout: FiniteDuration, + initTimeout: FiniteDuration, + minimumBloopJvm: Int, + retainedBloopVersion: BloopRifleConfig.BloopVersionConstraint +) +``` + +At a minimum users need 3 arguments: + +```scala + def default( + address: Address, + bloopClassPath: String => Either[Throwable, Seq[File]], + workingDir: File + ): BloopRifleConfig = +``` + +- `address| - the address of the server, either TCP or via a domain socket + path +- `bloopClassPath` - a function that takes a string and returns a sequence of + files, needed to download bloop binaries +- `workingDir` - the working directory of the server + +2. With config available users can use `BloopRifle.check` to check if Bloop is + running or `BloopRifle.start` to start the server. +3. Lastly, `BloopRifle.bsp` can be used to establish a connection to the server. + It will return a `BspConnection` class, which will have a `openSocket` method + available. + +#### Install Bloop Rifle + +```scala mdoc:rifle-releases +I am going to be replaced by the docs infrastructure. +``` + +Bloop Rifle is independent from Bloop but it's released with the same cadence +than the Bloop build server. Therefore, you can expect a build server version to +have an accompanying rifle version. + +### Open a BSP connection + +To open a BSP connection with Bloop's build server you need to follow the +[Build Server Discovery protocol][server-discovery]. BSP allow clients to +connect to a BSP server in a build-tool-independent way through BSP connection +files, a JSON file with build server metadata and an `argv` field that, if +shelled out, will establish a bsp connection with a server. + +The bloop BSP connection file is created automatically by any of the supported +bloop installation methods (in the global `.bsp` directory) or by any of its +build plugins (in the `.bsp` workspace directory). If you do not depend on a +build plugin or require the installation of bloop, you are required to create a +bloop BSP connection file to allow you and other servers follow the Build Server +Protocol. + +[server-discovery]: + https://github.com/build-server-protocol/build-server-protocol/blob/master/docs/overview/server-discovery.md diff --git a/docs/server.md b/docs/server.md index cf5c70b398..338bfb9cb9 100644 --- a/docs/server.md +++ b/docs/server.md @@ -4,8 +4,8 @@ title: Build Server Reference sidebar_label: Build Server --- -The build server is at the core of bloop. It runs in the background and is -the responsible for scheduling and running client actions. +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 @@ -13,97 +13,100 @@ 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. +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 start` +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. -For example, `bloop server`: +`bloop start` 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. For example, `bloop start`: -1. Finds the location of a bootstrapped jar automatically in the bloop installation - directory -1. Runs the server with the JVM options configured in `$HOME/.bloop/bloop.json`, see +1. Finds a JDK to use on your system or downloads a JDK if it's not available. +1. Runs the server with the JVM options configured via `BLOOP_JAVA_OPTS` + environment variable or `bloop.java-opts` property, see [custom Java options](#custom-java-options). -1. 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 `which bloop`. +1. Makes sure that the server is running it connects to that specific server.
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. +automatically in the background, you can use Bloop's built-in bloop rifle.
-### `bloop server` +### `bloop start` #### Usage -**Synopsis**: `bloop [FLAGS...] server [JVM_OPTS...] NAILGUN_PORT` - -* `NAILGUN_PORT` must be a free TCP port. For now, only ports on localhost are - supported. -* `JVM_OPTS` must be valid JVM arguments prefixed with `-J`, used to pass in - temporary jvm options to the server. For a permanent solution, add the options - to [`$HOME/.bloop/bloop.json`](#custom-java-options). - -#### Flags - -
-
--server-location (type: path)
-

Use the server jar or script in the given path

-
+```bash +Usage: bloop start [options] +Starts a Bloop instance, if none is running + +Help options: + --usage Print usage and exit + -h, -help, --help Print help message and exit + +Other options: + -v, --verbose Increase verbosity (can be specified multiple times) + -q, --quiet Decrease verbosity + --progress Use progress bars + --home, --home-directory string? + --java-home path Set the Java home directory + -j, --jvm jvm-name Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system` + -f, --force +``` -## Global settings for the server +### Custom Java options -Use the `$HOME/.bloop/bloop.json` file to configure the Bloop server. The -Bloop server must be restarted to pick up new configuration changes. +By default, Bloop server when run via the native launcher is configured to use: -### Custom Java options +``` + "-Xss4m", + "-XX:MaxInlineLevel=20", // Specific option for faster C2, ignored by GraalVM + "-XX:+UseZGC", // ZGC returns unused memory back to the OS, so Bloop does not occupy so much memory if unused + "-XX:ZUncommitDelay=30", + "-XX:ZCollectionInterval=5", + "-XX:+IgnoreUnrecognizedVMOptions", // Do not fail if an non-standard (-X, -XX) VM option is not recognized. + "-Dbloop.ignore-sig-int=true" +``` -Update the `javaOptions` field to configure custom Java options that should -be used when starting a new Bloop server. For example, use this to increase -the memory to Bloop. +Update the `BLOOP_JAVA_OPTS` env variable or `bloop.java-opts` property to +configure custom Java options that should be used when starting a new Bloop +server. For example, use this to increase the memory to Bloop. -```jsonc -// $HOME/.bloop/bloop.json -{ - "javaOptions": ["-Xmx16G"] -} +```bash +export BLOOP_JAVA_OPTS="-Xmx16G -XX:+UseZGC -Xss4m" ``` ### Custom Java home -Update the `javaHome` field declare what Java version the Bloop server should -run on. For example, use this to declare that Bloop should compile with JDK -11 or JDK 8. +By default Bloop CLI will try to find JDK 17 and up on your system, if it's not +possible it will download a JDK 17 from the internet. If you want to use a +different JDK, please make sure that JAVA_HOME is set correctly or use +`--java-home` option. -```jsonc -// $HOME/.bloop/bloop.json -{ - "javaHome": "/Library/Java/JavaVirtualMachines/jdk1.8.0_111.jdk" -} +```bash +bloop start --java-home "/Library/Java/JavaVirtualMachines/jdk1.8.0_111.jdk" ``` -The `java` binary should exist in `$JAVA_HOME/bin/java`. The Bloop server -will not start correctly if the `javaHome` field points directly to the -`java` binary. +The `java` binary should exist in `$JAVA_HOME/bin/java`. The Bloop server will +not start correctly if the `javaHome` field points directly to the `java` +binary. ## Automatic management 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. +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. -Both the bloop CLI and the launcher, the tool used by build clients to connect -to Bloop via BSP, will start the server if it's not running and connect to it. +Both the Bloop CLI and the Bloop Rifle, the tool used by build clients to +connect to Bloop via BSP, will start the server if it's not running and connect +to it. You can exit the server by running `bloop exit` from the CLI. You can also kill it with `kill`, the Activity Monitor in your machine or `htop`. ## Ignore exceptions in server logs -Bloop uses Nailgun, which sometimes prints exceptions in your server logs -such as: +Bloop uses Nailgun, which sometimes prints exceptions in your server logs such +as: ``` Unable to load nailgun-version.properties. diff --git a/website/i18n/en.json b/website/i18n/en.json index b479729735..6d8295b79d 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -74,8 +74,8 @@ "title": "Integrate with the Build Server", "sidebar_label": "Integration Guide" }, - "launcher-reference": { - "title": "Launcher Reference", + "bloop-rifle": { + "title": "Bloop Rifle", "sidebar_label": "Built-in Launcher" }, "offloading-compilation-sbt": { diff --git a/website/sidebars.json b/website/sidebars.json index 97d881f2f2..5cc68b34ea 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -24,7 +24,7 @@ "debugging-reference", "performance-guide", "server-reference", - "launcher-reference", + "bloop-rifle", "configuration-format", "contributing-guide" ]