Merge pull request #3155 from Gedochao/docs/scala-cli-as-scala-revamp

Update Scala CLI as `scala` related docs

Author: Gedochao

README.md

@@ -8,9 +8,9 @@ Scala CLI is a command-line tool to interact with the Scala language. It lets yo
 Scala code. (and more!) It shares some similarities with build tools, but it doesn't aim at supporting multi-module
 projects, nor to be extended via a task system.
 
-As of [SIP-46](https://github.com/scala/improvement-proposals/pull/46), Scala CLI has been accepted as the new `scala`
-command and is currently in the experimental phase. If you want to try it out, check for more
-details [here](https://scala-cli.virtuslab.org/docs/reference/scala-command/).
+As of Scala 3.5.0, Scala CLI has become the official `scala` runner of the language (for more information 
+refer to [SIP-46](https://github.com/scala/improvement-proposals/pull/46)). For more details on using Scala CLI
+via the `scala` command, refer to [this doc](https://scala-cli.virtuslab.org/docs/reference/scala-command/).
 
 ## Docs
 - user-facing documentation: [scala-cli.virtuslab.org](https://scala-cli.virtuslab.org/)

build.sc

@@ -172,6 +172,26 @@ trait DocsTests extends CrossSbtModule with ScalaCliScalafixModule with HasTests
   }
   def forkEnv = super.forkEnv() ++ extraEnv()
 
+  def constantsFile = T.persistent {
+    val dir  = T.dest / "constants"
+    val dest = dir / "Constants.scala"
+    val code =
+      s"""package sclicheck
+         |
+         |/** Build-time constants. Generated by mill. */
+         |object Constants {
+         |  def coursierOrg = "${Deps.coursier.dep.module.organization.value}"
+         |  def coursierCliModule = "${Deps.coursierCli.dep.module.name.value}"
+         |  def coursierCliVersion = "${Deps.Versions.coursierCli}"
+         |  def defaultScalaVersion = "${Scala.defaultUser}"
+         |}
+         |""".stripMargin
+    if (!os.isFile(dest) || os.read(dest) != code)
+      os.write.over(dest, code, createFolders = true)
+    PathRef(dir)
+  }
+  def generatedSources = super.generatedSources() ++ Seq(constantsFile())
+
   object test extends ScalaCliTests with ScalaCliScalafixModule {
     def forkEnv = super.forkEnv() ++ extraEnv() ++ Seq(
       "SCALA_CLI_EXAMPLES"                -> (os.pwd / "examples").toString,

modules/docs-tests/src/main/scala/sclicheck/sclicheck.scala

@@ -13,7 +13,7 @@ import scala.util.matching.Regex
 val SnippetBlock = """ *(`{2}`+)[^ ]+ title=([\w\d.\-/_]+) *""".r
 val CompileBlock = """ *(`{2}`+) *(\w+) +(compile|fail) *(?:title=([\w\d.\-/_]+))? *(power)? *""".r
 def compileBlockEnds(backticks: String) = s""" *$backticks *""".r
-val BashCommand                         = """ *```bash *(fail|run-fail)? *""".r
+val BashCommand                         = """ *```bash *(fail|run-fail)? *(clean)? *""".r
 val CheckBlock                          = """ *\<\!-- Expected(-regex)?: *""".r
 val CheckBlockEnd                       = """ *\--> *""".r
 val Clear                               = """ *<!--+ *clear *-+-> *""".r
@@ -35,8 +35,12 @@ enum Commands:
     case Check(patterns, regex, _) =>
       val kind = if regex then "regexes" else "patterns"
       s"last output matches $kind: ${patterns.map(p => s"'$p'").mkString(", ")}"
-    case Run(cmd, shouldFail, _) =>
-      val prefix = if shouldFail then "[failure expected] " else ""
+    case Run(cmd, shouldFail, shouldClean, _) =>
+      val prefix = shouldFail -> shouldClean match
+        case (true, true)  => "[failure expected, clean]"
+        case (true, false) => "[failure expected]"
+        case (false, true) => "[clean]"
+        case _             => ""
       cmd.mkString(prefix, " ", "")
     case Write(name, _, _) =>
       name
@@ -53,7 +57,7 @@ enum Commands:
     shouldFail: Boolean,
     power: Boolean
   )
-  case Run(scriptLines: Seq[String], shouldFail: Boolean, context: Context)
+  case Run(scriptLines: Seq[String], shouldFail: Boolean, shouldClean: Boolean, context: Context)
   case Check(patterns: Seq[String], regex: Boolean, context: Context)
   case Clear(context: Context)
 
@@ -100,8 +104,8 @@ def parse(content: Seq[String], currentCommands: Seq[Commands], context: Context
         compileBlockEnds(backticks)
       )
 
-    case BashCommand(failGroup) :: tail =>
-      parseMultiline(tail, Commands.Run(_, failGroup != null, context))
+    case BashCommand(failGroup, clean) :: tail =>
+      parseMultiline(tail, Commands.Run(_, failGroup != null, clean != null, context))
 
     case CheckBlock(regexOpt) :: tail =>
       val isRegex = regexOpt == "-regex"
@@ -187,15 +191,50 @@ def checkFile(file: os.Path, options: Options): Unit =
   val binDir = {
     val binDir0 = out / ".scala-cli"
     os.makeDir.all(binDir0)
-    val escapedCommand = options.scalaCliCommand
-      .map(arg => "\"" + arg.replace("\"", "\\\"") + "\"")
-      .mkString(" ")
-    val helperScript =
-      s"""#!/usr/bin/env bash
-         |exec $escapedCommand "$$@"
-         |""".stripMargin
-    os.write(binDir0 / "scala-cli", helperScript)
-    os.perms.set(binDir0 / "scala-cli", "rwxr-xr-x")
+
+    def createHelperScript(command: Seq[String], scriptName: String): Unit = {
+      val escapedCommand = command
+        .map(arg => "\"" + arg.replace("\"", "\\\"") + "\"")
+        .mkString(" ")
+      val scriptCode =
+        s"""#!/usr/bin/env bash
+           |exec $escapedCommand "$$@"
+           |""".stripMargin
+      os.write(binDir0 / scriptName, scriptCode)
+      os.perms.set(binDir0 / scriptName, "rwxr-xr-x")
+    }
+    createHelperScript(options.scalaCliCommand, "scala-cli")
+    createHelperScript(options.scalaCliCommand, "scala")
+    val coursierCliDep =
+      s"${Constants.coursierOrg}:${Constants.coursierCliModule}:${Constants.coursierCliVersion}"
+    createHelperScript(
+      options.scalaCliCommand ++ Seq(
+        "run",
+        "--dep",
+        coursierCliDep,
+        "--",
+        "launch",
+        s"scala:${Constants.defaultScalaVersion}",
+        "-M",
+        "dotty.tools.MainGenericRunner",
+        "--"
+      ),
+      "scala_legacy"
+    )
+    createHelperScript(
+      options.scalaCliCommand ++ Seq(
+        "run",
+        "--dep",
+        coursierCliDep,
+        "--",
+        "launch",
+        s"scala:${Constants.defaultScalaVersion}",
+        "-M",
+        "dotty.tools.dotc.Main",
+        "--"
+      ),
+      "scalac"
+    )
     binDir0
   }
   val extraEnv = {
@@ -239,7 +278,15 @@ def checkFile(file: os.Path, options: Options): Unit =
       res.exitCode
 
     cmd match
-      case Commands.Run(cmds, shouldFail, _) =>
+      case Commands.Run(cmds, shouldFail, shouldClean, _) =>
+        if shouldClean then
+          os.list(out)
+            .filterNot(_ == binDir)
+            .filterNot(_.last.endsWith(".scala"))
+            .filterNot(_.last.endsWith(".sc"))
+            .filterNot(_.last.endsWith(".java"))
+            .filterNot(_.last.endsWith(".md"))
+            .foreach(os.remove.all)
         val script = out / ".scala-build" / "run.sh"
         os.write.over(script, mkBashScript(cmds), createFolders = true)
         os.perms.set(script, "rwxr-xr-x")

project/deps.sc

@@ -145,7 +145,8 @@ object Deps {
   def caseApp          = ivy"com.github.alexarchambault::case-app:2.1.0-M28"
   def collectionCompat = ivy"org.scala-lang.modules::scala-collection-compat:2.12.0"
   // Force using of 2.13 - is there a better way?
-  def coursier = ivy"io.get-coursier:coursier_2.13:${Versions.coursier}"
+  def coursier    = ivy"io.get-coursier:coursier_2.13:${Versions.coursier}"
+  def coursierCli = ivy"io.get-coursier:coursier-cli_2.13:${Versions.coursierCli}"
   def coursierJvm = ivy"io.get-coursier:coursier-jvm_2.13:${Versions.coursier}"
     .exclude(("com.github.plokhotnyuk.jsoniter-scala", "jsoniter-scala-core_2.13"))
   def coursierLauncher = ivy"io.get-coursier:coursier-launcher_2.13:${Versions.coursier}"

website/docs/_advanced_install.mdx

@@ -4,6 +4,17 @@ import SectionAbout from "../src/components/SectionAbout"
 import DownloadButton from "../src/components/DownloadButton"
 import {currentOs} from "../src/components/osUtils";
 
+
+<SectionAbout title="Scala 3 installation"/>
+<div className="row">
+    <div className="col col--9 col--offset-1 padding--lg">
+        If you install Scala 3.5.0 or newer on your machine, you can use Scala CLI under the `scala` command. <br/>
+        For Scala 3 installation instructions refer <a  className="no_monospace" href="https://www.scala-lang.org/download/">here</a>.
+
+        Note that even when installing the latest Scala 3 version, its `scala` command may refer to an older Scala CLI version.
+        For the latest stable Scala CLI release it usually is necessary to install it separately.
+    </div>
+</div>
 <SectionAbout title="Advanced Installation">
     <div className="margin--lg"/>
     <Tabs
@@ -550,7 +561,7 @@ Scala Native page contains detailed [installation guide](https://scala-native.re
 </div></div>
 
 
-<SectionAbout title="Uninstall scala CLI">
+<SectionAbout title="Uninstall Scala CLI">
     <div className="margin--lg"/>
     <Tabs
         groupId="uninstall-specific"