Add docs for bloop interaction (#2608)

* Add headers to java properties docs

* Add document about interactions with Bloop

* Move bloop.md file to commands/misc/

* Update link to bloop docs, split paragraph into two

* Fix broken links

* Editorial fix

website/docs/commands/misc/bloop.md

@@ -0,0 +1,56 @@
+---
+title: Bloop ⚡️
+sidebar_position: 10
+---
+
+Scala CLI by default uses Bloop as a build server for compiling code. This approach has its advantages over the `scalac` compiler such as advanced caching and fast compile times, but the process is more complex.
+Fortunately for the users, Scala CLI fully manages the Bloop build server. This includes its whole lifecycle, which starts with fetching the artifacts.
+This document showcases the `bloop` subcommand that allows you manually manage the Bloop server.
+It also goes through the server's lifecycle and the interactions that Scala CLI has with it.
+
+:::caution
+The `bloop` sub-command is restricted and requires setting the `--power` option to be used.
+You can pass it explicitly or set it globally by running:
+
+    scala-cli config power true
+:::
+
+### Starting the server
+
+Whenever the code is compiled using Bloop, the first step is checking if the server is online, as it is launched as a daemon thread there's a chance it may have been launched during a past compilation.
+However, if the server is offline then Scala CLI needs to start and configure it.
+
+The configuration file for Bloop is created after analyzing the options collected from command line flags and using directives.
+The default location of the file is `.scala-build/bloop/project_name.json`.
+
+The last thing before launching the server is downloading its artifacts from Maven Central via Coursier if they are not already present in the local cache.
+:::tip
+When working in an environment with restricted access to the web, using Bloop can be disabled with the `--server=false` flag. Also, see the [section about the Offline mode](../../guides/offline.md).
+:::
+
+Bloop is started as a separate JVM process, parameters of this process can be configured using arguments passed to the invoked subcommand ([see compilation server options](../../reference/cli-options.md#compilation-server-options)).
+They also depend on the JVM version chosen for building the project, it cannot be higher than the version of the JVM running Bloop. If such a case is detected, the build server has to be restarted with a sufficiently high JVM.
+Note that the default version of the JVM for Bloop is 17, so if your `JAVA_HOME` refers to an older version of Java, Scala CLI will fetch the one you need. You can also override the JVM version Bloop runs on with the `--bloop-jvm` option.
+To start the Bloop server manually you can use the `bloop start` subcommand:
+```bash
+scala-cli --power bloop start
+```
+
+### Communicating with the server
+
+During the communication process, Scala CLI acts mostly as an intermediary between Bloop and the build client.
+The build client can be either the user invoking the tool from the command line or the IDE seeing Scala CLI as a build server.
+The behavior is mostly the same in both cases and is based on forwarding the messages. The messages being forwarded need to sometimes be edited as a result of preprocessing Scala CLI does, e.g. generating script sources.
+
+The main difference between running on the command line and serving an IDE is the information that gets through to the client.
+While an IDE receives all the messages that Bloop sends, the user only receives the relevant information, like warnings and errors coming from the compilation process.
+
+### Killing the server
+
+In general, the Bloop server is started as a daemon process that sticks around even after Scala CLI exits.
+The server can sometimes be automatically killed and restarted if a configuration change requires that, e.g. JVM version requested by the build is too high.
+
+However, sometimes it is needed to restart the Bloop server manually, for that the `bloop exit` subcommand can be used:
+```bash
+scala-cli --power bloop exit
+```

website/docs/commands/misc/default-file.md

@@ -1,6 +1,6 @@
 ---
 title: Default File ⚡️
-sidebar_position: 2
+sidebar_position: 20
 ---
 
 :::caution

website/docs/commands/misc/pgp.md

@@ -1,6 +1,6 @@
 ---
 title: PGP ⚡️
-sidebar_position: 18
+sidebar_position: 30
 ---
 
 :::caution

website/docs/guides/java-properties.md

@@ -4,8 +4,10 @@ sidebar_position: 8
 ---
 
 Although the Scala CLI runner can be used as a native image and thus will not always be run on the JVM it still supports Java properties.
-There are a couple ways to specify them:
-- as command line arguments, before the sub-command name and sources, when invoking `scala-cli`, e.g.
+There are a couple ways to specify them.
+
+### On the Command line
+Java properties can be passed as arguments, before the sub-command name and sources, when invoking `scala-cli`, e.g.
 ```bash ignore
     scala-cli '-Dcoursier.credentials=maven.pkg.github.com Private_Token:gh_token1234' run .
 ```
@@ -14,13 +16,16 @@ There are a couple ways to specify them:
 - `scala-cli -Dfoo=bar run .` would pass the java property into `scala-cli`.
   :::
 
-- save them in `.scala-jvmopts` file in the project's root, e.g.
+### File named `.scala-jvmopts` 
+You can also use a `.scala-jvmopts` file placed in the project's root, example file content:
 ```text
 -Dcoursier.credentials=maven.pkg.github.com Private_Token:gh_token1234
 -Dhttp.proxy=4.4.4.4
 -Dhttp.user=User2
 ```
-- set them globally using `scala-cli config`, e.g. 
+
+### Scala CLI's `config`
+It's also possible to use the `config` subcommand to set the properties globally:
 ```bash ignore
     scala-cli --power config -i java.properties "http.proxy=4.4.4.4" "http.user=User2" "coursier.credentials=..."
 ```
@@ -30,7 +35,8 @@ to update just a single value via the `config` command. Each update effectively
 list.
 :::
 
-- set them globally in `JAVA_OPTS` or `JDK_JAVA_OPTIONS` environment variable, e.g. 
+### `JAVA_OPTS` and `JDK_JAVA_OPTIONS`
+Scala CLI will also read environment variables `JAVA_OPTS` and `JDK_JAVA_OPTIONS` and scan them for Java properties:
 ```bash ignore
     export JAVA_OPTS="-Dhttp.proxy=4.4.4.4 -Dhttp.user=User2"
 ```

website/docs/under-the-hood.md

@@ -30,12 +30,14 @@ For this reason Scala CLI has the [clean](./commands/clean.md) command, which in
 
 We provide a more in-depth overview about how caching works in the [Scala CLI internals guide](./guides/internals.md).
 
-### Bloop and Coursier
+### Bloop
 
 To ensure the quickest compilation, Scala CLI uses and manages the [Bloop](https://scalacenter.github.io/bloop/) compilation server.
-We have a [detailed guide](./reference/bloop.md) that describes how Scala CLI interacts with the local Bloop server.
+We have a [guide](./commands/misc/bloop.md) that describes how Scala CLI interacts with the local Bloop server and how a user can do the same.
 The main point to know is that Scala CLI takes care of fetching and starting Bloop if needed, so you don't have to worry about it.
 
+### Coursier
+
 Scala CLI uses [Coursier](https://get-coursier.io/) to manage dependencies.
 It automatically downloads and unpacks a JVM if none is installed on your system, so that all its commands work fine even if a JVM isn't already installed.
 Scala CLI shares Coursier caches with other tools like [sbt](https://www.scala-sbt.org/), [Mill](https://github.com/com-lihaoyi/mill), or [Metals](https://scalameta.org/metals/).