Published 2013-12-01.
Last modified 2024-08-14.
Time to read: 1 minutes.
How to work with the Scala command-line compiler.
Scala Runner Command Line Options
The Scala command-line runner is called scala.
It drives the actual Scala compiler, scalac.
You can read about the Scala command-line runner’s options from the built-in help information.
This is the output of scala v2.13.14.
If you have another version of Scala then the output will differ.
Shell
$ scala -h Usage: scala <options> [<script|class|object|jar> <arguments>] or scala -help
All options to scalac (see scalac -help) are also allowed.
The first argument to scala after the options designates what to run.
If no argument is given, the Scala REPL, an interactive shell, is started.
Otherwise, the Scala runner will try to run the named target, either as a compiled class with a main method, a jar file with a Main-Class manifest header, or as a Scala source file to compile and run.
The REPL accepts expressions to evaluate. Try `:help` to see more commands.
The script runner will invoke the main method of a top-level object if it finds one; otherwise, the script code is run locally to a synthetic main method with arguments available in a variable `args`.
Options to scala which reach the Java runtime:
-Dname=prop passed directly to Java to set system properties -J<arg> -J is stripped and <arg> passed to Java as-is -nobootcp do not put the Scala jars on the boot classpath (slower)
Other startup options:
-i <file> preload <file> before starting the REPL -I <file> preload <file>, enforcing line-by-line interpretation -e <string> execute <string> as if it were in a source file -save save the compiled script in a jar for future use
If the runner does not correctly guess how to run the target:
-howtorun what to run <script|object|jar|repl|guess> (default: guess)
Scalac Command Line Options
As previously mentioned, the Scala compiler program is called scalac.
The advanced scalac options can be listed with the -X flag.
This is the output of scalac 2.13.14.
If you have another version of Scala then the options will differ.
Shell
$ scalac -X 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 artifacts. -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: `-opt:local`, `-opt:inline:<pattern>`; `-opt: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] -quickfix:<filters> Apply quick fixes provided by the compiler for warnings and errors to source files -release:<release> Compile for a version of the Java API and target class file. (8,9,10,11,12,13,14,15,16,[17]) -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. -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:inline:**. This can be dangerous. -target:<target> Target platform for object files. ([8],9,10,11,12,13,14,15,16,17) deprecated: Use -release instead to compile against the correct platform API.
All the experimental scalac options can be listed with the -Y option.
These are also referred to as private options.
Scala 2.13 removed all private options.
Shell
$ scalac -Y Usage: scalac <options> <source files>
Available private options: -Ybackend-parallelism <n> maximum worker threads for backend -Ybackend-worker-queue <n> backend threads worker queue size -Ybreak-cycles Attempt to break cycles encountered during typing [false] -Ycache-macro-class-loader:<policy> Policy for caching class loaders for macros that are dynamically loaded. Default: `none`, `help` to list choices. -Ycache-plugin-class-loader:<policy> Policy for caching class loaders for compiler plugins that are dynamically loaded. Default: `none`, `help` to list choices. -Ycheck:<phases> Check the tree at the end of <phases> -Ycompact-trees Use compact tree printer when displaying trees. [false] -Ydelambdafy:<strategy> Strategy used for translating lambdas into JVM code. (inline,[method]) -Ydump-classes <dir> Dump the generated bytecode to .class files (useful for reflective compilation that utilizes in-memory classloaders). -Ygen-asmp <dir> Generate a parallel output directory of .asmp files (ie ASM Textifier output). -Yimports:<import> Custom root imports, default is `java.lang,scala,scala.Predef`. -Yjar-compression-level <n> compression level to use when writing jar files -YjarFactory <classname> factory for jar files -Ymacro-annotations Enable support for macro annotations, formerly in macro paradise. [false] -Ymacro-classpath <path> The classpath used to reflectively load macro implementations, default is the compilation classpath. -Ymacro-expand:<policy> Control expansion of macros, useful for scaladoc and presentation compiler. ([normal],none,discard) -Ymacro-global-fresh-names Should fresh names in macros be unique across all compilation units [false] -Yno-completion Disable tab-completion in the REPL. [false] -Yno-flat-classpath-cache Do not cache flat classpath representation of classpath elements from jars across compiler instances. [false] -Yno-generic-signatures Suppress generation of generic signatures for Java. [false] -Yno-imports Compile without importing scala.*, java.lang.*, or Predef. [false] -Yno-predef Compile without importing Predef. [false] -Yopt-inline-heuristics:<strategy> Set the heuristics for inlining decisions. (at-inline-annotated,everything,[default]) -Ypatmat-exhaust-depth <n> off -Ypresentation-any-thread Allow use of the presentation compiler from any thread [false] -Ypresentation-debug Enable debugging output for the presentation compiler. [false] -Ypresentation-delay <n> Wait number of ms after typing before starting typechecking -Ypresentation-locate-source-file Enables legacy code in the classfile parser to locate a .scala file in the output directories corresponding to the SourceFile attribute .class file. [false] -Ypresentation-log <file> Log presentation compiler events into file -Ypresentation-replay <file> Replay presentation compiler events from file -Ypresentation-strict Do not report type errors in sources with syntax errors. [false] -Ypresentation-verbose Print information about presentation compiler tasks. [false] -Yprint-trees:<style> How to print trees when -Vprint is enabled. ([text],compact,format,text+format,diff) -Yprofile-destination <file> Profiling output - specify a file or `-` for console. -Yprofile-enabled Enable profiling. [false] -Yprofile-external-tool[:phases] Enable profiling for a phase using an external tool hook. Generally only useful for a single phase <phases> (default: typer) -Yprofile-run-gc[:phases] Run a GC between phases - this allows heap size to be accurate at the expense of more time. Specify a list of phases, or all <phases> (default: _) -Yprofile-trace <file> Capture trace of compilation in Chrome Trace format -Yrangepos Use range positions for syntax trees. [true] -Yrecursion <n> Set recursion depth used when locking symbols. -Yreify-copypaste Dump the reified trees in copypasteable representation. [false] -Yrelease:<packages> Expose platform packages hidden under --release -Yrepl-class-based Use classes to wrap REPL snippets instead of objects [true] -Yrepl-outdir <path> Write repl-generated classfiles to given output directory (use "" to generate a temporary dir) -Yrepl-use-magic-imports In the code that wraps REPL snippets, use magic imports rather than nesting wrapper object/classes [true] -Yresolve-term-conflict:<strategy> Resolve term conflicts. (package,object,[error]) -Yscriptrunner <classname> Specify a scala.tools.nsc.ScriptRunner (default, resident, shutdown, or a class name). -Yskip:<phases> Skip <phases> -Ystop-after:<phases> Stop after <phases> -Ystop-before:<phases> Stop before <phases> -Ytasty-no-annotations Disable support for reading annotations from TASTy, this will prevent safety features such as pattern match exhaustivity and reachability analysis. [false] -Ytasty-reader Enable support for reading Scala 3’s TASTy files, allowing consumption of libraries compiled with Scala 3 (provided they don’t use any Scala 3 only features). [false] -Ytrack-dependencies Record references to in unit.depends. Deprecated feature that supports SBT 0.13 with incOptions.withNameHashing(false) only. [true] -Yvalidate-pos:<phases> Validate positions after the given phases (implies -Yrangepos) <phases>
Deprecated settings: -Yscala3-implicit-resolution Use Scala-3-style downwards comparisons for implicit search and overloading resolution (see github.com/scala/scala/pull/6037). [false] deprecated: Use -Xsource:3 -Xsource-features:implicit-resolution instead
-- Note -- Boolean settings generally are false unless set: -Xdev -Xcheck-init:true -Xprompt:false Multi-valued settings are comma-separated: -Xlint:infer-any,unused,-missing-interpolator Phases are a list of names, ids, or ranges of ids: -Vprint:parser,typer,5-10 -Ylog:-4 Use _ to enable all: -language:_ -Vprint:_
If you want to know which are likely candidates to put in your SBT files,
grep for the word warn:
Shell
$ scalac -X |& grep warn -Xdev Indicates user is a developer - issue warnings about anything which seems amiss -Xlint:<warnings> Enable recommended warnings -Xmaxwarns <n> Maximum warnings to print
$ scalac -Y |& grep warn # Scala 2.13.1 removed all of these -Yinline-warnings Emit inlining warnings. (Normally supressed due to high volume) -Ywarn-adapted-args Warn if an argument list is modified to match the receiver. -Ywarn-all Enable all -Y warnings. -Ywarn-dead-code Warn when dead code is identified. -Ywarn-inaccessible Warn about inaccessible types in method signatures. -Ywarn-nullary-override Warn when non-nullary overrides nullary, e.g. `def foo()` over `def foo`. -Ywarn-nullary-unit Warn when nullary methods return Unit. -Ywarn-numeric-widen Warn when numerics are widened. -Ywarn-value-discard Warn when non-Unit expression results are unused.
© Copyright 1994-2024 Michael Slinn. All rights reserved.
If you would like to request to use this copyright-protected work in any manner,
please send an email.
This website was made using Jekyll and Mike Slinn’s Jekyll Plugins.