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 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

//> using file https://raw.githubusercontent.com/softwaremill/sttp/refs/heads/master/examples/src/main/scala/sttp/client4/examples/json/GetAndParseJsonCatsEffectCirce.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.8

//> 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.19.0

//> 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

//> using test.frameworks utest.runner.Framework munit.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