From 675221e1d8d16775c339178897003616709b503d Mon Sep 17 00:00:00 2001 From: Tomasz Godzik Date: Thu, 5 Sep 2024 17:51:17 +0200 Subject: [PATCH 1/2] docs: Update docs after recent changes - update usage - replace launcher docs Fixes https://github.com/scalacenter/bloop/issues/2417 --- .../scala/bloop/docs/ReleasesModifier.scala | 6 +- .../src/main/scala/bloop/docs/Sonatype.scala | 2 +- docs/build-tools/gradle.md | 6 - docs/contributing-guide.md | 16 +-- docs/guide/first-step.md | 2 +- docs/launcher.md | 96 -------------- docs/rifle.md | 96 ++++++++++++++ docs/server.md | 123 +++++++++--------- website/i18n/en.json | 4 +- website/sidebars.json | 2 +- 10 files changed, 175 insertions(+), 178 deletions(-) delete mode 100644 docs/launcher.md create mode 100644 docs/rifle.md 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..716f1b844e --- /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 option. + +```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 - it's the address of the server, either tcp or via a domain socket + path +- bloopClassPath - it's a function that takes a string and returns a sequence of + files, needed to download bloop binaries +- workingDir - it's 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 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..405e251b9e 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" ] From d33e869fe0c4225262cd49e530ceaf7c06c9b9fe Mon Sep 17 00:00:00 2001 From: Tomasz Godzik Date: Mon, 9 Sep 2024 17:11:07 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: adpi2 --- docs/rifle.md | 22 +++++++++++----------- docs/server.md | 4 ++-- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/rifle.md b/docs/rifle.md index 716f1b844e..b760587fa8 100644 --- a/docs/rifle.md +++ b/docs/rifle.md @@ -9,7 +9,7 @@ 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 +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 @@ -20,9 +20,9 @@ For an example of using Bloop rifle, see the 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 +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 option. + classpath options. ```scala final case class BloopRifleConfig( @@ -55,14 +55,14 @@ At a minimum users need 3 arguments: ): BloopRifleConfig = ``` -- address - it's the address of the server, either tcp or via a domain socket +- `address| - the address of the server, either TCP or via a domain socket path -- bloopClassPath - it's a function that takes a string and returns a sequence of +- `bloopClassPath` - a function that takes a string and returns a sequence of files, needed to download bloop binaries -- workingDir - it's the working directory of the server +- `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. +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. @@ -73,13 +73,13 @@ At a minimum users need 3 arguments: 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 +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 a bsp connection with Bloop's build server you need to follow the +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 diff --git a/docs/server.md b/docs/server.md index 405e251b9e..338bfb9cb9 100644 --- a/docs/server.md +++ b/docs/server.md @@ -78,7 +78,7 @@ export BLOOP_JAVA_OPTS="-Xmx16G -XX:+UseZGC -Xss4m" ### Custom Java home -By default Bloop cli will try to find JDK 17 and up on your system, if it's not +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. @@ -96,7 +96,7 @@ binary. 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 bloop rifle, the tool used by build clients to +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.