A Scala CLI gotcha: `using` directives broken by block comments.

scala-cli-using-gotcha.md

A gotcha when writing Scala CLI scripts

Block comments /* */ will break any using directives if placed before them in the file. Such script files will fail to compile, giving a generic message.

//> using file Utils.scala

See the docs for using directives: https://scala-cli.virtuslab.org/docs/guides/scripting/scripts/#define-source-files-in-using-directives

The docs point out that the file may not contain block comments before the using directive, or else compilation will break. It seems that, effectively, the using directive will get silently ignored if there is Scala code, /*, or /** placed before it in the file. Note that single-line comments // placed before the using directive do not cause the same issue.

See the example code below.

Example script to reproduce the issue

#!/usr/bin/env -S scala shebang --scala-version 3.7

// Single-line comment: no problem.
// Another single-line comment. Still no problem.
/* Block comment: this breaks everything! But if you delete it or move it down a couple lines, the script works once more. */
//> using file MyMath.scala

import MathTypes.Vector2
println(Vector2(1,5))

=> Running or compiling this broken script results in an error:

Compiling project (Scala 3.7.0, JVM (23))
[error] ./scripts/using-directive-broken-example-short.sc:8:8
[error] Not found: MathTypes
[error] import MathTypes.Vector2
[error]        ^^^^^^^^^
Error compiling project (Scala 3.7.0, JVM (23))
Compilation failed

The compilation error Not found on the import is not terribly informative, as the whole point of the using directive is to make that type available. In fact, it seems that in this case the using directive is silently failing or being ignored.

Additional notes

• Both block comments /* */ and ScalaDoc comments /** */ will cause this issue.
  • This aspect seems to be similar to another issue reported here which likewise has no issue with single-line comments: VirtusLab/scala-cli#2382
• The presence of the shebang line at the top of the file does not impact this issue either way.
• The verbose output from scala compile -O -verbose did not give much additional info about the using directive. The main hint to the user seems to be that there is only one "parsing ..." line, for the script itself, whereas in a successful compilation, the other source files get parsed as well, e.g. parsing /scripts/MyMath.scala.

Example of fixed script

#!/usr/bin/env -S scala shebang --scala-version 3.7

// Single-line comment: no problem.
// Another single-line comment. Still no problem.
//> using file MyMath.scala
/* Block comment: this was moved later in the file, and now the script works. */

import MathTypes.Vector2
println(Vector2(1,5))

Successful script compilation & execution:

Compiling project (Scala 3.7.0, JVM (23))
Compiled project (Scala 3.7.0, JVM (23))
Vector2(1.0,5.0)

source file MyMath.scala:

object MathTypes {
  case class Vector2(i: Double, j: Double)
}