Include environment variables in the automatically generated reference docs

Gedochao · Gedochao · commit 79672e723543 · 2024-08-07T15:42:33.000+02:00
diff --git a/modules/generate-reference-doc/src/main/scala/scala/cli/doc/GenerateReferenceDoc.scala b/modules/generate-reference-doc/src/main/scala/scala/cli/doc/GenerateReferenceDoc.scala
@@ -13,6 +13,7 @@ import java.util
 
 import scala.build.info.{ArtifactId, BuildInfo, ExportDependencyFormat, ScopedBuildInfo}
 import scala.build.internal.Constants
+import scala.build.internals.EnvVar
 import scala.build.options.{BuildOptions, BuildRequirements, WithBuildRequirements}
 import scala.build.preprocessing.directives.DirectiveHandler
 import scala.build.preprocessing.directives.DirectivesPreprocessingUtils.*
@@ -606,6 +607,34 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
     b.mkString
   }
 
+  private def envVarContent(groups: Seq[EnvVar.EnvVarGroup], onlyRestricted: Boolean): String = {
+    val b = new StringBuilder
+    b.section(
+      """---
+        |title: Environment variables
+        |sidebar_position: 7
+        |---""".stripMargin
+    )
+    b.section(
+      """Scala CLI uses environment variables to configure its behavior.
+        |Below you can find a list of environment variables used and recognized by Scala CLI.
+        |
+        |However, it should by no means be treated as an exhaustive list.
+        |Some tools and libraries Scala CLI integrates with may have their own, which may or may not be listed here.
+        |""".stripMargin
+    )
+    groups.foreach { group =>
+      b.section(
+        s"## ${group.groupName}",
+        group.all
+          .filter(ev => !ev.requiresPower || !onlyRestricted)
+          .map(ev => s"  - `${ev.name}`: ${if ev.requiresPower then "⚡ " else ""}${ev.description}")
+          .mkString("\n")
+      )
+    }
+    b.mkString
+  }
+
   def run(options: InternalDocOptions, args: RemainingArgs): Unit = {
 
     val scalaCli = new ScalaCliCommands(
@@ -644,16 +673,21 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
     )
     val restrictedDocsDir = os.rel / "scala-command"
 
+    val allEnvVarsContent        = envVarContent(EnvVar.allGroups, onlyRestricted = false)
+    val restrictedEnvVarsContent = envVarContent(Seq(EnvVar.ScalaCli), onlyRestricted = true)
+
     if (options.check) {
       val content = Seq(
         (os.rel / "cli-options.md")                           -> allCliOptionsContent,
         (os.rel / "commands.md")                              -> allCommandsContent,
         (os.rel / "directives.md")                            -> allDirectivesContent,
         (os.rel / "build-info.md")                            -> buildInfoContent,
+        (os.rel / "env-vars.md")                              -> allEnvVarsContent,
         (os.rel / restrictedDocsDir / "cli-options.md")       -> restrictedCliOptionsContent,
         (os.rel / restrictedDocsDir / "commands.md")          -> restrictedCommandsContent,
         (os.rel / restrictedDocsDir / "directives.md")        -> restrictedDirectivesContent,
-        (os.rel / restrictedDocsDir / "runner-specification") -> scalaOptionsReference
+        (os.rel / restrictedDocsDir / "runner-specification") -> scalaOptionsReference,
+        (os.rel / restrictedDocsDir / "env-vars.md")          -> restrictedEnvVarsContent
       )
       var anyDiff = false
       for ((dest, content0) <- content) {
@@ -678,6 +712,7 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
       maybeWrite(options.outputPath / "commands.md", allCommandsContent)
       maybeWrite(options.outputPath / "directives.md", allDirectivesContent)
       maybeWrite(options.outputPath / "build-info.md", buildInfoContent)
+      maybeWrite(options.outputPath / "env-vars.md", allEnvVarsContent)
 
       maybeWrite(
         options.outputPath / restrictedDocsDir / "cli-options.md",
@@ -692,6 +727,10 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
         options.outputPath / restrictedDocsDir / "runner-specification.md",
         scalaOptionsReference
       )
+      maybeWrite(
+        options.outputPath / restrictedDocsDir / "env-vars.md",
+        restrictedEnvVarsContent
+      )
     }
   }
 }
diff --git a/website/docs/reference/env-vars.md b/website/docs/reference/env-vars.md
@@ -0,0 +1,68 @@
+---
+title: Environment variables
+sidebar_position: 7
+---
+
+Scala CLI uses environment variables to configure its behavior.
+Below you can find a list of environment variables used and recognized by Scala CLI.
+
+However, it should by no means be treated as an exhaustive list.
+Some tools and libraries Scala CLI integrates with may have their own, which may or may not be listed here.
+
+
+## Scala CLI
+  - `SCALA_CLI_CONFIG`: Scala CLI configuration file path
+  - `SCALA_CLI_HOME`: Scala CLI home directory
+  - `SCALA_CLI_INTERACTIVE`: Interactive mode toggle
+  - `SCALA_CLI_INTERACTIVE_INPUTS`: Interactive mode inputs
+  - `SCALA_CLI_POWER`: Power mode toggle
+  - `SCALA_CLI_PRINT_STACK_TRACES`: Print stack traces toggle
+  - `SCALA_CLI_SODIUM_JNI_ALLOW`: Allow to load libsodiumjni
+  - `SCALA_CLI_VENDORED_ZIS`: Toggle io.github.scala_cli.zip.ZipInputStream
+
+## Java
+  - `JAVA_HOME`: Java installation directory
+  - `JAVA_OPTS`: Java options
+  - `JDK_JAVA_OPTIONS`: JDK Java options
+
+## Bloop
+  - `BLOOP_COMPUTATION_CORES`: ⚡ Number of computation cores to be used
+  - `BLOOP_DAEMON_DIR`: ⚡ Bloop daemon directory
+  - `BLOOP_JAVA_OPTS`: ⚡ Bloop Java options
+  - `BLOOP_MODULE`: ⚡ Bloop default module
+  - `BLOOP_PORT`: ⚡ Bloop default port
+  - `BLOOP_SCALA_VERSION`: ⚡ Bloop default Scala version
+  - `BLOOP_VERSION`: ⚡ Bloop default version
+  - `BLOOP_SERVER`: ⚡ Bloop default host
+  - `SCALA_CLI_EXTRA_TIMEOUT`: ⚡ Extra timeout
+
+## Coursier
+  - `COURSIER_BIN_DIR`: Coursier app binaries directory
+  - `COURSIER_CACHE`: Coursier cache location
+  - `COURSIER_CONFIG_DIR`: Coursier configuration directory
+  - `COURSIER_CREDENTIALS`: Coursier credentials
+  - `INSIDE_EMACS`: Emacs toggle
+  - `COURSIER_EXPERIMENTAL`: Experimental mode toggle
+  - `COURSIER_JNI`: Coursier JNI toggle
+  - `COURSIER_MODE`: Coursier mode (can be set to 'offline')
+  - `COURSIER_NO_TERM`: Terminal toggle
+  - `COURSIER_PROGRESS`: Progress bar toggle
+  - `COURSIER_REPOSITORIES`: Coursier repositories
+  - `COURSIER_VENDORED_ZIS`: Toggle io.github.scala_cli.zip.ZipInputStream
+  - `CS_MAVEN_HOME`: Coursier Maven home directory
+
+## Spark
+  - `SPARK_HOME`: ⚡ Spark installation directory
+
+## Miscellaneous
+  - `PATH`: The app path variable
+  - `DYLD_LIBRARY_PATH`: Runtime library paths on Mac OS X
+  - `LD_LIBRARY_PATH`: Runtime library paths on Linux
+  - `PATHEXT`: Executable file extensions on Windows
+  - `SHELL`: The currently used shell
+  - `VCVARSALL`: Visual C++ Redistributable Runtimes
+  - `ZDOTDIR`: Zsh configuration directory
+
+## Internal
+  - `CI`: ⚡ Marker for running on the CI
+
diff --git a/website/docs/reference/scala-command/env-vars.md b/website/docs/reference/scala-command/env-vars.md
@@ -0,0 +1,22 @@
+---
+title: Environment variables
+sidebar_position: 7
+---
+
+Scala CLI uses environment variables to configure its behavior.
+Below you can find a list of environment variables used and recognized by Scala CLI.
+
+However, it should by no means be treated as an exhaustive list.
+Some tools and libraries Scala CLI integrates with may have their own, which may or may not be listed here.
+
+
+## Scala CLI
+  - `SCALA_CLI_CONFIG`: Scala CLI configuration file path
+  - `SCALA_CLI_HOME`: Scala CLI home directory
+  - `SCALA_CLI_INTERACTIVE`: Interactive mode toggle
+  - `SCALA_CLI_INTERACTIVE_INPUTS`: Interactive mode inputs
+  - `SCALA_CLI_POWER`: Power mode toggle
+  - `SCALA_CLI_PRINT_STACK_TRACES`: Print stack traces toggle
+  - `SCALA_CLI_SODIUM_JNI_ALLOW`: Allow to load libsodiumjni
+  - `SCALA_CLI_VENDORED_ZIS`: Toggle io.github.scala_cli.zip.ZipInputStream
+
