Merge pull request #3075 from Gedochao/maintenance/more-env-vars

Add more env vars & generate reference docs for them
VirtusLab · Aug 8, 2024 · 57d6335 · 57d6335
2 parents 5fe92a7 + 79672e7
commit 57d6335
Show file tree

Hide file tree

Showing 4 changed files with 192 additions and 5 deletions.
diff --git a/modules/core/src/main/scala/scala/build/internals/EnvVar.scala b/modules/core/src/main/scala/scala/build/internals/EnvVar.scala
@@ -57,7 +57,7 @@ object EnvVar {
         }""".stripMargin
     }
   }
-  def allGroups: Seq[EnvVarGroup] = Seq(ScalaCli, Java, Coursier, Spark, Misc, Internal)
+  def allGroups: Seq[EnvVarGroup] = Seq(ScalaCli, Java, Bloop, Coursier, Spark, Misc, Internal)
   def all: Seq[EnvVar]            = allGroups.flatMap(_.all)
   def allBsp: Seq[EnvVar]         = all.filter(_.passToIde)
   object Java extends EnvVarGroup {
@@ -83,16 +83,44 @@ object EnvVar {
     val dyldLibraryPath = EnvVar("DYLD_LIBRARY_PATH", "Runtime library paths on Mac OS X")
     val ldLibraryPath   = EnvVar("LD_LIBRARY_PATH", "Runtime library paths on Linux")
     val pathExt         = EnvVar("PATHEXT", "Executable file extensions on Windows")
+    val pwd             = EnvVar("PWD", "Current working directory", passToIde = false)
     val shell           = EnvVar("SHELL", "The currently used shell")
     val vcVarsAll       = EnvVar("VCVARSALL", "Visual C++ Redistributable Runtimes")
     val zDotDir         = EnvVar("ZDOTDIR", "Zsh configuration directory")
+    val mavenHome       = EnvVar("MAVEN_HOME", "Maven home directory")
   }
 
   object Coursier extends EnvVarGroup {
     override def groupName: String = "Coursier"
-    override def all               = Seq(coursierCache, coursierMode)
-    val coursierCache              = EnvVar("COURSIER_CACHE", "Coursier cache location")
-    val coursierMode = EnvVar("COURSIER_MODE", "Coursier mode (can be set to 'offline')")
+    override def all = Seq(
+      coursierBinDir,
+      coursierCache,
+      coursierConfigDir,
+      coursierCredentials,
+      insideEmacs,
+      coursierExperimental,
+      coursierJni,
+      coursierMode,
+      coursierNoTerm,
+      coursierProgress,
+      coursierRepositories,
+      coursierVendoredZis,
+      csMavenHome
+    )
+    val coursierBinDir       = EnvVar("COURSIER_BIN_DIR", "Coursier app binaries directory")
+    val coursierCache        = EnvVar("COURSIER_CACHE", "Coursier cache location")
+    val coursierConfigDir    = EnvVar("COURSIER_CONFIG_DIR", "Coursier configuration directory")
+    val coursierCredentials  = EnvVar("COURSIER_CREDENTIALS", "Coursier credentials")
+    val coursierExperimental = EnvVar("COURSIER_EXPERIMENTAL", "Experimental mode toggle")
+    val coursierJni          = EnvVar("COURSIER_JNI", "Coursier JNI toggle")
+    val coursierMode         = EnvVar("COURSIER_MODE", "Coursier mode (can be set to 'offline')")
+    val coursierNoTerm       = EnvVar("COURSIER_NO_TERM", "Terminal toggle")
+    val coursierProgress     = EnvVar("COURSIER_PROGRESS", "Progress bar toggle")
+    val coursierRepositories = EnvVar("COURSIER_REPOSITORIES", "Coursier repositories")
+    val coursierVendoredZis =
+      EnvVar("COURSIER_VENDORED_ZIS", "Toggle io.github.scala_cli.zip.ZipInputStream")
+    val csMavenHome = EnvVar("CS_MAVEN_HOME", "Coursier Maven home directory")
+    val insideEmacs = EnvVar("INSIDE_EMACS", "Emacs toggle")
   }
 
   object ScalaCli extends EnvVarGroup {
@@ -108,6 +136,7 @@ object EnvVar {
       vendoredZipInputStream
     )
     val config            = EnvVar("SCALA_CLI_CONFIG", "Scala CLI configuration file path")
+    val extraTimeout      = Bloop.bloopExtraTimeout.copy(requiresPower = false)
     val home              = EnvVar("SCALA_CLI_HOME", "Scala CLI home directory")
     val interactive       = EnvVar("SCALA_CLI_INTERACTIVE", "Interactive mode toggle")
     val interactiveInputs = EnvVar("SCALA_CLI_INTERACTIVE_INPUTS", "Interactive mode inputs")
@@ -124,6 +153,35 @@ object EnvVar {
     val sparkHome = EnvVar("SPARK_HOME", "Spark installation directory", requiresPower = true)
   }
 
+  object Bloop extends EnvVarGroup {
+    override def groupName: String = "Bloop"
+    override def all = Seq(
+      bloopComputationCores,
+      bloopDaemonDir,
+      bloopJavaOpts,
+      bloopModule,
+      bloopPort,
+      bloopScalaVersion,
+      bloopVersion,
+      bloopServer,
+      bloopExtraTimeout
+    )
+    val bloopComputationCores = EnvVar(
+      "BLOOP_COMPUTATION_CORES",
+      "Number of computation cores to be used",
+      requiresPower = true
+    )
+    val bloopDaemonDir = EnvVar("BLOOP_DAEMON_DIR", "Bloop daemon directory", requiresPower = true)
+    val bloopJavaOpts  = EnvVar("BLOOP_JAVA_OPTS", "Bloop Java options", requiresPower = true)
+    val bloopModule    = EnvVar("BLOOP_MODULE", "Bloop default module", requiresPower = true)
+    val bloopPort      = EnvVar("BLOOP_PORT", "Bloop default port", requiresPower = true)
+    val bloopScalaVersion =
+      EnvVar("BLOOP_SCALA_VERSION", "Bloop default Scala version", requiresPower = true)
+    val bloopVersion      = EnvVar("BLOOP_VERSION", "Bloop default version", requiresPower = true)
+    val bloopServer       = EnvVar("BLOOP_SERVER", "Bloop default host", requiresPower = true)
+    val bloopExtraTimeout = EnvVar("SCALA_CLI_EXTRA_TIMEOUT", "Extra timeout", requiresPower = true)
+  }
+
   object Internal extends EnvVarGroup {
     override def groupName: String = "Internal"
     def all                        = Seq(ci)

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
+