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 scalacOption option
//> using option option
//> using scalacOptions option1 option2 …
//> using options option1 option2 …
//> using test.scalacOption option
//> using test.option option
//> using test.scalacOptions option1 option2 …
//> using test.options option1 option2 …
Examples
//> using option -Xasync
//> using options -Xasync -Xfatal-warnings
//> using test.option -Xasync
//> using test.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
//> using deps org:name:ver org:name:ver
//> using dependencies org:name:ver org:name:ver
//> using test.dep org:name:ver
//> using test.deps org:name:ver org:name:ver
//> using test.dependencies org:name:ver org:name:ver
//> using compileOnly.dep org:name:ver
//> using compileOnly.deps org:name:ver org:name:ver
//> using compileOnly.dependencies org:name:ver org:name:ver
//> using scalafix.dep org:name:ver
//> using scalafix.deps org:name:ver org:name:ver
//> using scalafix.dependencies org:name:ver org:name:ver
Examples
//> using dep com.lihaoyi::os-lib:0.9.1
//> using dep tabby:tabby:0.2.3,url=https://github.com/bjornregnell/tabby/releases/download/v0.2.3/tabby_3-0.2.3.jar
//> using test.dep org.scalatest::scalatest:3.2.10
//> using test.dep org.scalameta::munit:0.7.29
//> using compileOnly.dep com.github.plokhotnyuk.jsoniter-scala::jsoniter-scala-macros:2.23.2
//> using scalafix.dep com.github.xuwei-k::scalafix-rules:0.5.1
Java options
Add Java options which will be passed when running an application.
//> using javaOpt options
//> using javaOptions options`
//> using test.javaOpt options
//> using test.javaOptions options`
Examples
//> using javaOpt -Xmx2g -Dsomething=a
//> using test.javaOpt -Dsomething=a
Java properties
Add Java properties
//> using javaProp key=value
//> using javaProp key
//> using test.javaProp key=value
//> using test.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 …
//> using test.jar path
//> using test.jars path1 path2 …
//> using source.jar path
//> using source.jars path1 path2 …
//> using test.source.jar path
//> using test.source.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
//> using javacOptions options
//> using test.javacOpt options
//> using test.javacOptions 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)+
//> using platforms (jvm|scala-js|js|scala-native|native)+
Examples
//> using platform scala-js
//> using platforms 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 …
//> using test.resourceDir path
//> using test.resourceDirs path1 path2 …
Examples
//> using resourceDir ./resources
//> using test.resourceDir ./resources
Scala Native options
Add Scala Native options
//> using nativeGc immix|commix|boehm|none
//> using nativeMode debug|release-fast|release-size|release-full
//> using nativeLto none|full|thin
//> using nativeVersion value
//> using nativeCompile value1 value2 …
//> using nativeLinking value1 value2 …
//> using nativeClang value
//> using nativeClangPP value
//> using nativeClangPp value
//> using nativeEmbedResources true|false
//> using nativeEmbedResources
//> using nativeTarget application|library-dynamic|library-static
//> using nativeMultithreading true|false
//> using nativeMultithreading
Examples
//> using nativeGc immix
//> using nativeMode debug
//> using nativeLto full
//> using nativeVersion 0.5.7
//> using nativeCompile -flto=thin
//> using nativeLinking -flto=thin
//> using nativeClang ./clang
//> using nativeClangPP ./clang++
//> using nativeEmbedResources
//> using nativeEmbedResources true
//> using nativeTarget library-dynamic
//> using nativeMultithreading
//> using nativeMultithreading false
Scala.js options
Add Scala.js options
//> using jsVersion value
//> using jsMode value
//> using jsNoOpt true|false
//> using jsNoOpt
//> using jsModuleKind value
//> using jsCheckIr true|false
//> using jsCheckIr
//> using jsEmitSourceMaps true|false
//> using jsEmitSourceMaps
//> using jsEsModuleImportMap value
//> using jsSmallModuleForPackage value1 value2 …
//> using jsDom true|false
//> using jsDom
//> using jsHeader value
//> using jsAllowBigIntsForLongs true|false
//> using jsAllowBigIntsForLongs
//> using jsAvoidClasses true|false
//> using jsAvoidClasses
//> using jsAvoidLetsAndConsts true|false
//> using jsAvoidLetsAndConsts
//> using jsModuleSplitStyleStr value
//> using jsEsVersionStr value
//> using jsEmitWasm true|false
//> using jsEmitWasm
Examples
//> using jsVersion 1.18.2
//> using jsMode mode
//> using jsNoOpt
//> using jsModuleKind common
//> using jsCheckIr
//> using jsEmitSourceMaps
//> using jsEsModuleImportMap importmap.json
//> using jsSmallModuleForPackage test
//> using jsDom
//> using jsHeader "#!/usr/bin/env node "
//> using jsAllowBigIntsForLongs
//> using jsAvoidClasses
//> using jsAvoidLetsAndConsts
//> using jsModuleSplitStyleStr smallestmodules
//> using jsEsVersionStr es2017
//> using jsEmitWasm
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.7.0, 'default' version for typelevel toolkit: 0.1.29
//> using toolkit version
//> using test.toolkit` version
Examples
//> using toolkit 0.7.0
//> using toolkit default
//> using test.toolkit default