Use scala & scala_legacy in old runner migration guide; verify them with docs-tests

Author: Gedochao

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

@@ -187,15 +187,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 = {

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/guides/introduction/old-runner-migration.md

@@ -29,15 +29,12 @@ Scala CLI is available as the `scala` command alongside the Scala distribution i
 Yes, even though its usage has been deprecated, it is still available under the `scala_legacy` command. 
 However, it is likely to be dropped in a future version.
 
-```bash ignore
-scala_legacy
+```bash
+scala_legacy -version
 # [warning] MainGenericRunner class is deprecated since Scala 3.5.0, and Scala CLI features will not work.
 # [warning] Please be sure to update to the Scala CLI launcher to use the new features.
 # [warning] Check the Scala 3.5.0 release notes to troubleshoot your installation.
-# Welcome to Scala 3.5.0 (17, Java OpenJDK 64-Bit Server VM).
-# Type in expressions for evaluation. Or try :help.
-#                                                                                                                  
-# scala> 
+# Scala code runner version 3.5.0 -- Copyright 2002-2024, LAMP/EPFL
 ```
 
 ## How has the passing of arguments been changed from the old `scala` runner to Scala CLI?
@@ -46,55 +43,63 @@ Let us take a closer look on how the old runner handled arguments when compared
 
 ### The old ways
 
-In the old `scala` runner, the first argument was treated as the input source, while the second and following arguments
+In the old runner, the first argument was treated as the input source, while the second and following arguments
 were considered program arguments.
 
-```bash ignore
-scala Source.scala programArg1 programArg2
+```scala title=Source.scala
+@main def main(args: String*): Unit = println(args.mkString(" "))
+```
+
+```bash
+scala_legacy Source.scala programArg1 programArg2
 ```
 
 Since everything after the first argument had to be arbitrarily read as a program argument, regardless of format, all
 runner options had to be passed before the source input.
 
-```bash ignore
-scala -save script.sc programArg1 programArg2
+```bash
+scala_legacy -save Source.scala programArg1 programArg2
 ```
 
 ### The ways of Scala CLI
 
 With Scala CLI's default way of handling arguments, inputs and program arguments have to be
 divided by `--`. There is no limit for the number of either.
 
+```scala title=Source2.scala
+def placeholder = println("Example extra source")
+```
+
 ```bash ignore
-scala-cli Source1.scala Source2.scala -- programArg1 programArg2
+scala Source.scala Source2.scala -- programArg1 programArg2
 ```
 
 Additionally, a Scala CLI sub-command can be passed before the inputs section.
 For example, to call the above example specifying the `run` sub-command explicitly, pass it like this:
 
-```bash ignore
-scala-cli run Source1.scala Source2.scala -- programArg1 programArg2
+```bash
+scala run Source.scala Source2.scala -- programArg1 programArg2
 ```
 
 More on sub-commands can be found [here](../../commands/basics.md).
 
 Runner options can be passed on whatever position in the inputs section (before `--`).
 For example, all the following examples are correct ways to specify the Scala version explicitly as `3.2`
 
-```bash ignore
-scala-cli -S 3.2 Source1.scala Source2.scala -- programArg1 programArg2
-scala-cli Source1.scala -S 3.2 Source2.scala -- programArg1 programArg2
-scala-cli Source1.scala Source2.scala -S 3.2 -- programArg1 programArg2
+```bash
+scala -S 3.2 Source.scala Source2.scala -- programArg1 programArg2
+scala Source.scala -S 3.2 Source2.scala -- programArg1 programArg2
+scala Source.scala Source2.scala -S 3.2 -- programArg1 programArg2
 ```
 
 :::note
 The exception to this rule are the launcher options, like `--cli-version` or `--cli-scala-version`.
 Those have to be passed before the inputs section (before any source inputs).
 
-For example, to explicitly specify the launcher should run Scala CLI `v0.1.20`, pass it like this:
+For example, to explicitly specify the launcher should run Scala CLI `v1.5.0`, pass it like this:
 
-```bash ignore
-scala-cli --cli-version 0.1.20 Source1.scala Source2.scala -- programArg1 programArg2
+```bash
+scala --cli-version 1.5.0 Source.scala Source2.scala -- programArg1 programArg2
 ```
 
 Also, if a Scala CLI sub-command is being passed explicitly, all launcher options have to be passed before the
@@ -103,7 +108,7 @@ sub-command.
 For example, to call [the `package` sub-command](../../commands/package.md) using the nightly CLI version, do it like this:
 
 ```bash ignore
-scala-cli --cli-version nightly package --help
+scala --cli-version nightly package --help
 ```
 
 :::
@@ -114,8 +119,8 @@ To provide better support for shebang scripts, Scala CLI
 has [a dedicated `shebang` sub-command](../../commands/shebang.md), which handles arguments similarly to the old `scala`
 script.
 
-```bash ignore
-scala-cli shebang Source.scala programArg1 programArg2
+```bash
+scala shebang Source.scala programArg1 programArg2
 ```
 
 The purpose of the `shebang` sub-command is essentially to only be used in a shebang header (more
@@ -231,12 +236,12 @@ object Main {
 
 <ChainedSnippets>
 
-```bash ignore
-scala Main.scala Hello world
+```bash
+scala_legacy Main.scala Hello world
 ```
 
 ```bash
-scala-cli Main.scala -- Hello world
+scala Main.scala -- Hello world
 ```
 
 ```text
@@ -259,7 +264,7 @@ In other words, when explicitly declaring a main class when working with Scala C
 file.
 
 ```bash
-scala-cli main-in-script.sc -- Hello world 
+scala main-in-script.sc -- Hello world 
 # no output will be printed
 ```
 
@@ -280,7 +285,7 @@ However, it is supported by Scala CLI.
 <ChainedSnippets>
 
 ```bash
-scala-cli script.sc -- Hello world
+scala script.sc -- Hello world
 ```
 
 ```text
@@ -303,7 +308,7 @@ However, both the old Scala `3.x` runner as well as Scala CLI do not support it.
 <ChainedSnippets>
 
 ```bash fail
-scala-cli script.scala -- Hello world
+scala script.scala -- Hello world
 ```
 
 ```text
@@ -347,15 +352,15 @@ That is, all arguments starting with the second were treated as program args, ra
 This is in contrast with the Scala CLI default way of handling arguments, where inputs and program arguments have to be
 divided by `--`.
 
-```bash ignore
-scala-cli Source1.scala Source2.scala -- programArg1 programArg2
+```bash
+scala Source.scala Source2.scala -- programArg1 programArg2
 ```
 
 To better support shebang scripts, Scala CLI has a dedicated `shebang` sub-command, which handles arguments similarly to
 the old `scala` script.
 
-```bash ignore
-scala-cli shebang Source.scala programArg1 programArg2
+```bash
+scala shebang Source.scala programArg1 programArg2
 ```
 
 For more concrete examples on how to change the shebang header in your existing scripts, look below.
@@ -409,17 +414,18 @@ implicitly run any compiled class files it would find.
 ```
 
 This syntax has been dropped and is no longer supported with the new `scala` runner.
-```bash ignore
+```bash
 scalac hello.scala
-scala hello # NOTE: this syntax is not supported by Scala CLI
+scala_legacy hello # NOTE: this syntax is not supported by Scala CLI
 # Hello
 ```
 
 With Scala CLI, all inputs have to be passed explicitly, so any compiled classes in the current working directory 
 would be ignored unless passed explicitly. 
 ```bash ignore
+scala clean .
 scalac hello.scala
-scala-cli run -cp .
+scala run -cp .
 # Hello
 ```
 
@@ -428,8 +434,9 @@ If only the classpath is passed with `-cp`, then the `run` sub-command can't be
 will default to the REPL (as there are no explicit source file inputs present).
 
 ```bash ignore
+scala clean .
 scalac hello.scala
-scala-cli -cp .
+scala -cp .
 # Welcome to Scala 3.5.0 (17, Java OpenJDK 64-Bit Server VM).
 # Type in expressions for evaluation. Or try :help.
 #                                                                                                                  
@@ -440,8 +447,9 @@ scala-cli -cp .
 It is possible to explicitly specify the main class to be run (for example, if there are multiple main classes 
 in the build). The `run` sub-command becomes optional then, as passing `-M` indicates the intention to run something.
 ```bash
+scala clean .
 scalac hello.scala
-scala-cli -cp . -M hello
+scala -cp . -M hello
 # Hello
 ```
 
@@ -451,16 +459,17 @@ with the `compile` sub-command, rather than the `scalac` script.
 
 You don't have to specify the class files location, Scala CLI won't recompile them if they are up to date.
 ```bash ignore
-scala-cli compile hello.scala
-scala-cli hello.scala
+scala clean hello.scala
+scala compile hello.scala
+scala hello.scala
 # Hello
 ```
 
 Alternatively, you can also specify the location for the compiled classes explicitly, and then add them 
 to the classpath, as you would with `scalac`.
-```bash ignore
-scala-cli compile hello.scala -d compiled_classes
-scala-cli hello.scala
+```bash
+scala compile hello.scala -d compiled_classes
+scala run -cp compiled_classes
 # Hello
 ```
 :::

website/docs/reference/scala-command/index.md

@@ -49,7 +49,7 @@ bit slower than a native launcher.
 Also, the specified version (and potentially any of its dependencies, if they are not already installed) would be
 downloaded if it's not available in the local cache, so it may require additional setup for isolated environments.
 
-```bash ignore
+```bash
 scala --cli-version 1.5.0 version
 # Scala CLI version: 1.5.0
 # Scala version (default): 3.5.0
@@ -82,13 +82,10 @@ migrate any existing scripts and automations to Scala CLI under either `scala` o
 command may be dropped at some point in the future.
 :::
 
-```bash ignore
-scala_legacy
+```bash
+scala_legacy -version
 # [warning] MainGenericRunner class is deprecated since Scala 3.5.0, and Scala CLI features will not work.
 # [warning] Please be sure to update to the Scala CLI launcher to use the new features.
 # [warning] Check the Scala 3.5.0 release notes to troubleshoot your installation.
-# Welcome to Scala 3.5.0 (17, Java OpenJDK 64-Bit Server VM).
-# Type in expressions for evaluation. Or try :help.
-#                                                                                                                  
-# scala> 
+# Scala code runner version 3.5.0 -- Copyright 2002-2024, LAMP/EPFL
 ```