Skip to main content

Directives

This document describes as scala-cli behaves if run as scala command. See more information in SIP-46

This document is a specification of the scala runner. For now it uses documentation specific to Scala CLI but at some point it may be refactored to provide more abstract documentation. Documentation is split into sections in the spirit of RFC keywords (MUST, SHOULD).

MUST have directives:​

Compiler options​

Add Scala compiler options

//> using option option

//> using options option1 option2 …

Examples​

//> using option -Xasync

//> using test.option -Xasync

//> using options -Xasync -Xfatal-warnings

Compiler plugins​

Adds compiler plugins

using plugin org:name:ver

Examples​

//> using plugin org.typelevel:::kind-projector:0.13.2

Dependency​

Add dependencies

//> using dep org:name:ver

Examples​

//> using dep com.lihaoyi::os-lib:0.9.1

//> using test.dep org.scalatest::scalatest:3.2.10

//> using test.dep org.scalameta::munit:0.7.29

//> using dep "tabby:tabby:0.2.3,url=https://github.com/bjornregnell/tabby/releases/download/v0.2.3/tabby_3-0.2.3.jar"

Java options​

Add Java options which will be passed when running an application.

//> using javaOpt options

Examples​

//> using javaOpt -Xmx2g, -Dsomething=a

//> using test.javaOpt -Dsomething=a

Java properties​

Add Java properties

//> using javaProp key=value

//> using javaProp key

Examples​

//> using javaProp foo1=bar, foo2

//> using test.javaProp foo3=bar foo4

Main class​

Specify default main class

//> using mainClass main-class

Examples​

//> using mainClass HelloWorld

Scala version​

Set the default Scala version

//> using scala version+

Examples​

//> using scala 3.0.2

//> using scala 2.13

//> using scala 2

//> using scala 2.13.6, 2.12.16

SHOULD have directives:​

Custom JAR​

Manually add JAR(s) to the class path

//> using jar path

//> using jars path1 path2 …

Examples​

//> using jar /Users/alexandre/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/com/chuusai/shapeless_2.13/2.3.7/shapeless_2.13-2.3.7.jar

//> using test.jar /Users/alexandre/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/com/chuusai/shapeless_2.13/2.3.7/shapeless_2.13-2.3.7.jar

//> using sourceJar /path/to/custom-jar-sources.jar

//> using sourceJars /path/to/custom-jar-sources.jar /path/to/another-jar-sources.jar

//> using test.sourceJar /path/to/test-custom-jar-sources.jar

Custom sources​

Manually add sources to the project. Does not support chaining, sources are added only once, not recursively.

//> using file path

//> using files path1 path2 …

Examples​

//> using file utils.scala

Exclude sources​

Exclude sources from the project

//> using exclude pattern

//> using exclude pattern1 pattern2 …

Examples​

//> using exclude utils.scala

//> using exclude "examples/*" "*/resources/*"

//> using exclude "*.sc"

JVM version​

Use a specific JVM, such as 14, adopt:11, or graalvm:21, or system. scala-cli uses coursier to fetch JVMs, so you can use cs java --available to list the available JVMs.

//> using jvm value

Examples​

//> using jvm 11

//> using jvm adopt:11

//> using jvm graalvm:21

Java home​

Sets Java home used to run your application or tests

//> using javaHome path

Examples​

//> using javaHome /Users/Me/jdks/11

Javac options​

Add Javac options which will be passed when compiling sources.

//> using javacOpt options

Examples​

//> using javacOpt -source 1.8 -target 1.8

//> using test.javacOpt -source 1.8 -target 1.8

Platform​

Set the default platform to Scala.js or Scala Native

//> using platform (jvm|scala-js|js|scala-native|native)+

Examples​

//> using platform scala-js

//> using platform jvm scala-native

Repository​

Add repositories for dependency resolution.

Accepts predefined repositories supported by Coursier (like sonatype:snapshots or m2Local) or a URL of the root of Maven repository

//> using repository repository

Examples​

//> using repository jitpack

//> using repository sonatype:snapshots

//> using repository m2Local

//> using repository https://maven-central.storage-download.googleapis.com/maven2

Resource directories​

Manually add a resource directory to the class path

//> using resourceDir path

//> using resourceDirs path1 path2 …

Examples​

//> using resourceDir ./resources

//> using test.resourceDir ./resources

Scala Native options​

Add Scala Native options

//> using nativeGc value

//> using nativeMode value

//> using nativeLto value

//> using nativeVersion value

//> using nativeCompile value1 value2 …

//> using nativeLinking value1 value2 …

//> using nativeClang value

//> using nativeClangPP value

//> using nativeEmbedResources true|false

//> using nativeTarget application|library-dynamic|library-static

Examples​

//> using nativeVersion 0.4.0

Scala.js options​

Add Scala.js options

//> using jsVersion value

//> using jsMode value

//> using jsNoOpt true|false

//> using jsModuleKind value

//> using jsSmallModuleForPackage value1 value2 …

//> using jsCheckIr true|false

//> using jsEmitSourceMaps true|false

//> using jsDom true|false

//> using jsHeader value

//> using jsAllowBigIntsForLongs true|false

//> using jsAvoidClasses true|false

//> using jsAvoidLetsAndConsts true|false

//> using jsModuleSplitStyleStr value

//> using jsEsVersionStr value

//> using jsEmitWasm true|false

//> using jsEsModuleImportMap value

Examples​

//> using jsModuleKind common

Test framework​

Set the test framework

//> using testFramework class-name

Examples​

//> using testFramework utest.runner.Framework

Toolkit​

Use a toolkit as dependency (not supported in Scala 2.12), 'default' version for Scala toolkit: 0.5.0, 'default' version for typelevel toolkit: 0.1.27

//> using toolkit version

Examples​

//> using toolkit 0.1.0

//> using toolkit default

//> using test.toolkit default