Skip to content

More words and explain -release #2364

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Aug 2, 2022
Merged

More words and explain -release #2364

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a902b65
More words and explain -release
som-snytt Mar 31, 2022
9a94362
Review improvements and improvisations
som-snytt Jul 31, 2022
f5f6696
No Scala 3 aliases after all
som-snytt Jul 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 40 additions & 22 deletions _overviews/compiler-options/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,17 +25,13 @@ title: Scala Compiler Options

## Introduction

Scala compiler `scalac` offers various **compiler options**, also referred to as **compiler flags**, to change how to compile your program.
The Scala compiler `scalac` offers various **compiler options**, or **flags**, that change the compiler's default behavior. Some options just generate more compiler output in the form of diagnostics or warnings, while others change the result of compilation.

Nowadays, most people are not running `scalac` from the command line.
Instead, they use sbt, an IDE, and other tools as their interface to the compiler.
Therefore they may not even have `scalac` installed, and won't think to do `man scalac`.
The Scala command `scala`, which runs scripts or compiled code, accepts the same options as the `scalac` compiler, plus a few more that determine how to run a program.

This page comes to the rescue for the people to find…

* What compiler options `scalac` offers
* How to use compiler options
Options may be specified on the command line to `scalac` or in the configuration of a build tool or IDE.

The Scala distribution includes a `man` page. If Scala is installed as a system command, that documentation may be available from `man scalac`.

## How to use compiler options

Expand All @@ -44,34 +40,47 @@ This page comes to the rescue for the people to find…
```bash
scalac [ <options> ] <source files>
```
Boolean flags are specified in the usual way:

`scalac -Werror -Xlint Hello.scala`

Options that require arguments use "colon" syntax:

`scalac -Vprint:parser,typer`

E.g. `scalac -encoding utf8 -Xfatal-warnings Hello.scala`
Options that take just a single argument accept traditional syntax:

Default paths can be listed by running a command line tool:
`scalac -d /tmp`

Conventionally, options have a prefix `-V` if they show "verbose" output;
`-W` to manage warnings; `-X` for extended options that modify tool behavior;
`-Y` for private options with limited support, where `Y` may suggest forking behavior.
Several options have historical aliases, such as `-Xfatal-warnings` for `-Werror`.

In Scala 2, default paths can be listed by running a tool in the distribution:
```
scala scala.tools.util.PathResolver [ <options> ]
```


That can help debug errors in options such as `--classpath`.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does not work for me:

$ scala scala.tools.util.PathResolver
Ignoring spurious arguments: scala.tools.util.PathResolver
Welcome to Scala 3.1.3 (17.0.3, Java OpenJDK 64-Bit Server VM).
Type in expressions for evaluation. Or try :help.
                                                                                                                               
scala>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Am I doing something wrong?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's scala 2, scala.tools vs dotty.tools. Worth mentioning.

### Use compiler options with sbt


Here is a typical configuration of the `scalacOptions` setting in `sbt`:

```scala
scalacOptions ++= Seq(
"-encoding", "utf8", // Option and arguments on same line
"-Xfatal-warnings", // New lines for each options
"-deprecation",
"-unchecked",
scalacOptions ++= Seq( // use ++= to add to existing options
"-encoding", "utf8", // if an option takes an arg, supply it on the same line
"-feature", // then put the next option on a new line for easy editing
"-language:implicitConversions",
"-language:higherKinds",
"-language:existentials",
"-language:postfixOps"
)
"-unchecked",
"-Werror",
"-Xlint", // exploit "trailing comma" syntax so you can add an option without editing this line
) // for "trailing comma", the closing paren must be on the next line
```
The convention is always to append to the setting with `++=` and to supply one option per line.


Normally the last option will have a trailing comma so that `git diff` is a bit cleaner when options are added.

{% for category in site.data.compiler-options %}
<h2>{{ category.category }}</h2>
Expand Down Expand Up @@ -116,6 +125,15 @@ scalacOptions ++= Seq(

{% endfor %}

### Targeting a version of the JVM

Applications or libraries targeting the JVM may wish to specify a target version.

The `-release` option specifies the target version, such as "8" or "18".

Like the option for `javac`, it allows building against an earlier version of the JDK. It will compile against the API for that version and also output class files for that version.

The deprecated option `-target` does not compile against the desired API, but only specifies a target class file format.

## Additional resources

Expand Down