Skip to main content

Compile

Scala CLI compiles your code with its compile command:

object Hello {
  def main(args: Array[String]): Unit =
    println("Hello")
}
scala-cli compile Hello.scala

Note that most Scala CLI commands automatically compile your code, if necessary. The compile command is useful if you want to check that your code compiles (or to see the compilation warnings, if any occur) without running it or packaging it.

The most common compile options are shown below. For a full list of options, run scala-cli compile --help, or check the options linked in the reference documentation.

Test scope​

--test makes Scala CLI compile main and test scopes:

//> using dep org.scalameta::munit:1.0.2
class Test extends munit.FunSuite {
  test("sample") {
    assert(2 + 2 == 4)
  }
}
scala-cli compile --test Sample.test.scala

Watch mode​

--watch makes Scala CLI watch your code for changes, and re-compiles it upon any change:

scala-cli compile --watch Hello.scala
Compiling project-cef76d561e (1 Scala source)
Compiled 'project-cef76d561e'
Watching sources, press Ctrl+C to exit.
Compiling project-cef76d561e (1 Scala source)
Compiled 'project-cef76d561e'
Watching sources, press Ctrl+C to exit.

Scala version​

Scala CLI uses the latest stable version of Scala which was tested in Scala CLI (see our list of Supported Scala Versions). You can specify the Scala version you'd like to use with --scala:

scala-cli compile --scala 2.13.15 Hello.scala

Scala CLI works with all major 2.12.x, 2.13.x, and 3.x Scala versions.

--scala also accepts "short" Scala versions, such as 2.12, 2, or 3. In this case, it picks the highest corresponding stable Scala version:

scala-cli compile --scala 2.12 Hello.scala
scala-cli compile --scala 2 Hello.scala
scala-cli compile --scala 3 Hello.scala

Scala Nightlies​

The nightly builds of Scala compiler are the unstable ones which are published on a nightly basis.

To use the latest Scala 2 and Scala 3 nightly builds, pass 2.nightly and 3.nightly, respectively. You can also request the last 2.12.nightly and 2.13.nightly versions. 2.13.nightly is the same as 2.nightly. Moreover, passing in the 3.{sub binary number}.nightly format, such as 3.0.nightly or 3.1.nightly is accepted, too.

Scala CLI takes care of fetching the nightly builds of Scala 2 and Scala 3 from different repositories, without you having to pass their addresses as input after the --repo flag.

For compiling with the latest Scala 2 nightly build:

scala-cli Hello.scala -S 2.nightly

For compiling with the latest Scala 3 nightly build:

scala-cli Hello.scala -S 3.nightly

For compiling with a specific nightly build you have the full version:

scala-cli Hello.scala -S 2.13.9-bin-4505094

For setting this inside scala files, use using directives:

//> using scala 2.nightly
//> using scala 3.nightly
//> using scala 2.13.9-bin-4505094

Dependencies​

You can add dependencies on the command-line with --dependency:

scala-cli compile Hello.scala \
  --dependency org.scala-lang.modules::scala-parallel-collections:1.0.4

Note that --dependency is only meant as a convenience. You should favor adding dependencies in the source files themselves via using directives.

You can also add simple JAR files — those that don’t have transitive dependencies — as dependencies, with --jar:

scala-cli compile Hello.scala --jar /path/to/library.jar

See the Dependency management guide for more details.

Scala compiler options​

Passing compiler options with -O​

All Scala compiler options can be passed to Scala CLI with -O:

scala-cli compile Hello.scala -O -deprecation -O -Xlint:infer-any
[warn] ./Hello.scala:3:7: method x in class Some is deprecated (since 2.12.0): Use .value instead.
[warn]   opt.x
[warn]       ^

Passing a value to a compiler option requires another -O:

scala-cli -O -Xshow-phases -O -color -O never
note

Scala CLI uses bloop by default, which at times gets in the way of getting the full compiler output. In the case of some compiler options it may be necessary to turn bloop off with --server=false. The Scala CLI team is actively trying to minimize such cases, but for the time being it's a useful workaround.

Passing compiler options with using directives​

It is also possible to pass compiler options with the appropriate using directives.

A single option can be passed like this:

//> using option -new-syntax
@main def hello = if true then println("Hello")

It's also possible to pass a value to the option with the same directive:

//> using option -release 11

import java.net.http.HttpRequest

There's a separate directive for passing multiple options at one time:

//> using options -new-syntax -rewrite -source:3.2-migration

@main def hello = if (true) println("Hello")

Compiler options recognised even when passed without -O​

For ease of use many compiler options can be passed as-is to Scala CLI, without the need of passing after -O:

scala-cli compile Hello.scala -Xlint:infer-any

Compiling project (1 Scala source)
[warn] ./Hello.scala:2:11: a type was inferred to be `Any`; this may indicate a programming error.
[warn]   val l = List("a", true, 2, new Object)
[warn]           ^
Compiled project

Those include:

  • all options which start with:
    • -g
    • -language
    • -opt
    • -P
    • -target
    • -source
    • -V
    • -W
    • -X
    • -Y
  • the following flags:
    • -nowarn
    • -feature
    • -deprecation
    • -rewrite
    • -old-syntax
    • -new-syntax
    • -indent
    • -no-indent
  • the following options which accept values (which can be passed similarly to any regular Scala CLI option values)
    • -encoding
    • -release
    • -color
    • -classpath
    • -d

All options mentioned above are assumed to be Scala compiler options and are being passed as such to the compiler even without -O. (However, they can still be passed with -O, regardless.)

note

Some compiler options (e.g. -new-syntax) may be Scala-version-specific. Thus, it may happen that Scala CLI will pass those to the compiler, but they will not be recognised if they're not supported in a given Scala version. In such a case, refer to the --scalac-help output while passing the appropriate version with -S.

Java options for the compiler​

There are two ways to pass Java options to the compiler:

  • --bloop-java-opt when using the build server, which is the default, e.g. --bloop-java-opt -XX:MaxHeapSize=8g
  • //> using options or --scalac-opt with arguments prefixed by -J, e.g. //> using options -J-XX:MaxHeapSize=8g, this will work only when the build server is disabled (with --server=false).

Compiler options redirected to Scala CLI alternatives​

In a few cases, certain compiler options are being auto-redirected to a corresponding Scala CLI-specific option for better integration with other functionalities of the tool. The redirection happens even when the options are passed with -O, making them effectively aliases for their Scala CLI counterparts.

Those include:

  • -classpath being redirected to --classpath
  • -d being redirected to --compilation-output

Scala compiler help​

Certain compiler options allow to view relevant help. Inputs aren't required when those are passed. (since they would be disregarded anyway)

Those include:

  • -help
  • -V
  • -W
  • -X
  • -Y
scala-cli -S 2.12.17 -Xshow-phases

     phase name  id  description
     ----------  --  -----------
         parser   1  parse source into ASTs, perform simple desugaring
          namer   2  resolve names, attach symbols to named trees
 packageobjects   3  load package objects
          typer   4  the meat and potatoes: type the trees
         patmat   5  translate match expressions
 superaccessors   6  add super accessors in traits and nested classes
     extmethods   7  add extension methods for inline classes
        pickler   8  serialize symbol tables
      refchecks   9  reference/override checking, translate nested objects
        uncurry  10  uncurry, translate function values to anonymous classes
         fields  11  synthesize accessors and fields, add bitmaps for lazy vals
      tailcalls  12  replace tail calls by jumps
     specialize  13  @specialized-driven class and method specialization
  explicitouter  14  this refs to outer pointers
        erasure  15  erase types, add interfaces for traits
    posterasure  16  clean up erased inline classes
     lambdalift  17  move nested functions to top level
   constructors  18  move field definitions into constructors
        flatten  19  eliminate inner classes
          mixin  20  mixin composition
        cleanup  21  platform-specific cleanups, generate reflective calls
     delambdafy  22  remove lambdas
            jvm  23  generate JVM bytecode
       terminal  24  the last phase during a compilation run

You can also view the Scala compiler help for a particular Scala version with --scalac-help, which is just an alias for -O -help. Please note that -help passed without -O will show the Scala CLI help instead.

scala-cli -S 2.13.8 --scalac-help
Usage: scalac <options> <source files>

Standard options:
  -Dproperty=value             Pass -Dproperty=value directly to the runtime system.
  -J<flag>                     Pass <flag> directly to the runtime system.
  -P:<plugin>:<opt>            Pass an option to a plugin
  -V                           Print a synopsis of verbose options. [false]
  -W                           Print a synopsis of warning options. [false]
  -Werror                      Fail the compilation if there are any warnings. [false]
  -X                           Print a synopsis of advanced options. [false]
  -Y                           Print a synopsis of private options. [false]
  -bootclasspath <path>        Override location of bootstrap class files.
  -classpath <path>            Specify where to find user class files.
  -d <directory|jar>           destination for generated classfiles.
  -dependencyfile <file>       Set dependency tracking file.
  -deprecation                 Emit warning and location for usages of deprecated APIs. See also -Wconf. [false]
  -encoding <encoding>         Specify character encoding used by source files.
  -explaintypes                Explain type errors in more detail. [false]
  -extdirs <path>              Override location of installed extensions.
  -feature                     Emit warning and location for usages of features that should be imported explicitly. See also -Wconf. [false]
  -g:<level>                   Set level of generated debugging info. (none,source,line,[vars],notailcalls)
  -help                        Print a synopsis of standard options [false]
  -javabootclasspath <path>    Override java boot classpath.
  -javaextdirs <path>          Override java extdirs classpath.
  -language:<features>         Enable or disable language features
  -no-specialization           Ignore @specialize annotations. [false]
  -nobootcp                    Do not use the boot classpath for the scala jars. [false]
  -nowarn                      Generate no warnings. [false]
  -opt:<optimizations>         Enable optimizations, `help` for details.
  -opt-inline-from:<patterns>  Patterns for classfile names from which to allow inlining, `help` for details.
  -opt-warnings:<warnings>     Enable optimizer warnings, `help` for details.
  -print                       Print program with Scala-specific features removed. [false]
  -release <release>           Compile for a specific version of the Java platform. Supported targets: 6, 7, 8, 9
  -rootdir <path>              The absolute path of the project root directory, usually the git/scm checkout. Used by -Wconf.
  -sourcepath <path>           Specify location(s) of source files.
  -target:<target>             Target platform for object files. ([8],9,10,11,12,13,14,15,16,17,18)
  -toolcp <path>               Add to the runner classpath.
  -unchecked                   Enable additional warnings where generated code depends on assumptions. See also -Wconf. [false]
  -uniqid                      Uniquely tag all identifiers in debugging output. [false]
  -usejavacp                   Utilize the java.class.path in classpath resolution. [false]
  -usemanifestcp               Utilize the manifest in classpath resolution. [false]
  -verbose                     Output messages about what the compiler is doing. [false]
  -version                     Print product version and exit. [false]
  @<file>                      A text file containing compiler arguments (options and source files) [false]

Deprecated settings:
  -optimize                    Enables optimizations. [false]
                               deprecated: Since 2.12, enables -opt:l:inline -opt-inline-from:**. See -opt:help.

Scala compiler plugins​

Use --compiler-plugin to add compiler plugin dependencies:

scala-cli compile Hello.scala --compiler-plugin org.typelevel:::kind-projector:0.13.3 --scala 2.13.13

Printing a class path​

--print-class-path makes scala-cli compile print a class path:

scala-cli compile --print-class-path Hello.scala
/work/.scala/project-cef76d561e/classes:~/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/org/scala-lang/scala-library/2.12.14/scala-library-2.12.14.jar:~/Library/Caches/ScalaCli/local-repo/0.1.0/org.virtuslab.scala-cli/runner_2.12/0.0.1-SNAPSHOT/jars/runner_2.12.jar:~/Library/Caches/ScalaCli/local-repo/0.1.0/org.virtuslab.scala-cli/stubs/0.0.1-SNAPSHOT/jars/stubs.jar

This is handy when working with other tools. For example, you can pass this class path to java -cp:

java -cp "$(scala-cli compile --print-class-path Hello.scala)" Hello
Hello

Note that you should favor the run command to run your code, rather than running java -cp. The class path obtained this way is only meant for scenarios where Scala CLI doesn't offer a more convenient option.

If you need the class path to consist only of JAR files, pass --as-jar. This packages the Scala CLI project byte code in a JAR file, rather than leaving it in a directory:

scala-cli compile --print-class-path Hello.scala --as-jar
/work/.scala-build/project_103be31561-475e1607f5/jar/library.jar:~/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/org/scala-lang/scala3-library_3/3.2.2/scala3-library_3-3.2.2.jar:~/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/org/scala-lang/scala-library/2.13.10/scala-library-2.13.10.jar

JVM options​

--javac-opt lets you add javac options which will be passed when compiling sources.

scala-cli Hello.scala --javac-opt source --javac-opt 1.8 --javac-opt target --javac-opt 1.8

You can also add javac options with the using directive //> using javacOpt:

//> using javacOpt source 1.8 target 1.8

Exclude sources​

To exclude specific source files or entire directories from a Scala CLI project, use the exclude directive or command line parameter --exclude along with a pattern:

  • an absolute path: /root/path/to/your/project/Main.scala
  • a relative path: src/main/scala/Main.scala
  • a glob pattern: *.sc
note

The exclude directive should be placed in your project.scala file, which Scala CLI uses to determine the project root directory. For more details on project.file, see the Project root directory reference.

For example, to exclude all files in the example/scala directory, add the following directive to your project.file file:

//> using exclude example/scala

Compile-Only Dependencies​

Compile-only dependencies, allow to include certain libraries exclusively at the time of the compilation. These dependencies are added to the class path during compilation, but won't be included when the application is run.

To declare a compile-only dependency, you should use the compileOnly.dep directive or --compile-lib command line option. For instance, to include the jsoniter-scala-macros library at compile-time, you would use:

//> using compileOnly.dep com.github.plokhotnyuk.jsoniter-scala::jsoniter-scala-macros:2.23.2

or by using the --compile-lib command line option:

scala-cli Hello.scala --compile-lib "com.github.plokhotnyuk.jsoniter-scala::jsoniter-scala-macros:2.23.2"