From 6898753bef12c3c837151c4b805ed3a478d6ee84 Mon Sep 17 00:00:00 2001 From: Piotr Chabelski Date: Tue, 6 Aug 2024 14:26:31 +0200 Subject: [PATCH 1/3] Add Bloop-specific environment variables --- .../scala/scala/build/internals/EnvVar.scala | 33 ++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/modules/core/src/main/scala/scala/build/internals/EnvVar.scala b/modules/core/src/main/scala/scala/build/internals/EnvVar.scala index a206c42b82..9fa0a1abae 100644 --- 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,6 +83,7 @@ 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") @@ -108,6 +109,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 +126,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) From c6550c2a8464f044ba73251d233bc64680d14bcf Mon Sep 17 00:00:00 2001 From: Piotr Chabelski Date: Tue, 6 Aug 2024 14:37:07 +0200 Subject: [PATCH 2/3] Add Coursier-specific environment variables --- .../scala/scala/build/internals/EnvVar.scala | 33 +++++++++++++++++-- 1 file changed, 30 insertions(+), 3 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 index 9fa0a1abae..7ca43bed65 100644 --- a/modules/core/src/main/scala/scala/build/internals/EnvVar.scala +++ b/modules/core/src/main/scala/scala/build/internals/EnvVar.scala @@ -87,13 +87,40 @@ object EnvVar { 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 { From 79672e723543658b6925211e5f684d11ac7a62e0 Mon Sep 17 00:00:00 2001 From: Piotr Chabelski Date: Tue, 6 Aug 2024 16:02:17 +0200 Subject: [PATCH 3/3] Include environment variables in the automatically generated reference docs --- .../scala/cli/doc/GenerateReferenceDoc.scala | 41 ++++++++++- website/docs/reference/env-vars.md | 68 +++++++++++++++++++ .../docs/reference/scala-command/env-vars.md | 22 ++++++ 3 files changed, 130 insertions(+), 1 deletion(-) create mode 100644 website/docs/reference/env-vars.md create mode 100644 website/docs/reference/scala-command/env-vars.md 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 index 8e813a00ff..5878a14351 100644 --- 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 new file mode 100644 index 0000000000..aca67ade3e --- /dev/null +++ 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 new file mode 100644 index 0000000000..122506d2b4 --- /dev/null +++ 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 +