diff --git a/README.md b/README.md index 49eb207f8..6a32febe4 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,15 @@ This repository contains the source for the Scala documentation website, as well as the source for "Scala Improvement Process" (SIP) documents. +## Dependencies ## + +This site uses a Jekyll, a Ruby framework. You'll need Ruby and Bundler installed; see [Jekyll installation instructions](https://jekyllrb.com/docs/installation/) for the details. + ## Quickstart ## To build and view the site locally: - gem install --user-install bundler jekyll + bundle install bundle exec jekyll serve -I ([Trouble on MacOS?](https://github.com/scala/docs.scala-lang/issues/1150)) @@ -53,10 +57,6 @@ Small changes, or corrected typos will generally be pulled in right away. Large existing documents will be thoroughly reviewed-- please keep in mind that, generally, new documents must be very well-polished, complete, and maintained in order to be accepted. -## Dependencies ## - -This site uses a Jekyll, a Ruby framework. You'll need Ruby and Bundler installed; see [Jekyll installation instructions](https://jekyllrb.com/docs/installation/) for the details. - ## Building & Viewing ## cd into the directory where you cloned this repository, then install the required gems with `bundle install`. This will automatically put the gems into `./vendor/bundle`. diff --git a/_overviews/scala3-migration/external-resources.md b/_overviews/scala3-migration/external-resources.md index 9f968c6df..1055f4bc9 100644 --- a/_overviews/scala3-migration/external-resources.md +++ b/_overviews/scala3-migration/external-resources.md @@ -2,7 +2,7 @@ title: External Resources type: chapter description: This section lists external resources about the migration to Scala 3. -num: 28 +num: 29 previous-page: plugin-kind-projector next-page: --- diff --git a/_overviews/scala3-migration/incompat-contextual-abstractions.md b/_overviews/scala3-migration/incompat-contextual-abstractions.md index 502df62f8..ea5947f2e 100644 --- a/_overviews/scala3-migration/incompat-contextual-abstractions.md +++ b/_overviews/scala3-migration/incompat-contextual-abstractions.md @@ -2,7 +2,7 @@ title: Contextual Abstractions type: section description: This chapter details all incompatibilities caused by the redesign of contextual abstractions -num: 18 +num: 19 previous-page: incompat-dropped-features next-page: incompat-other-changes --- diff --git a/_overviews/scala3-migration/incompat-dropped-features.md b/_overviews/scala3-migration/incompat-dropped-features.md index afdbe0022..845a58b14 100644 --- a/_overviews/scala3-migration/incompat-dropped-features.md +++ b/_overviews/scala3-migration/incompat-dropped-features.md @@ -2,7 +2,7 @@ title: Dropped Features type: section description: This chapter details all the dropped features -num: 17 +num: 18 previous-page: incompat-syntactic next-page: incompat-contextual-abstractions --- diff --git a/_overviews/scala3-migration/incompat-other-changes.md b/_overviews/scala3-migration/incompat-other-changes.md index 90c04abab..57dc8998d 100644 --- a/_overviews/scala3-migration/incompat-other-changes.md +++ b/_overviews/scala3-migration/incompat-other-changes.md @@ -2,7 +2,7 @@ title: Other Changed Features type: section description: This chapter details all incompatibilities caused by changed features -num: 19 +num: 20 previous-page: incompat-contextual-abstractions next-page: incompat-type-checker --- diff --git a/_overviews/scala3-migration/incompat-syntactic.md b/_overviews/scala3-migration/incompat-syntactic.md index 7ce3b2110..0e88e2b03 100644 --- a/_overviews/scala3-migration/incompat-syntactic.md +++ b/_overviews/scala3-migration/incompat-syntactic.md @@ -2,7 +2,7 @@ title: Syntactic Changes type: section description: This chapter details all the incompatibilities caused by syntactic changes -num: 16 +num: 17 previous-page: incompatibility-table next-page: incompat-dropped-features --- diff --git a/_overviews/scala3-migration/incompat-type-checker.md b/_overviews/scala3-migration/incompat-type-checker.md index 6c6728d4f..09a6ea0bc 100644 --- a/_overviews/scala3-migration/incompat-type-checker.md +++ b/_overviews/scala3-migration/incompat-type-checker.md @@ -2,7 +2,7 @@ title: Type Checker type: section description: This chapter details the unsoundness fixes in the type checker -num: 20 +num: 21 previous-page: incompat-other-changes next-page: incompat-type-inference --- diff --git a/_overviews/scala3-migration/incompat-type-inference.md b/_overviews/scala3-migration/incompat-type-inference.md index 387bc918c..a5f1552c0 100644 --- a/_overviews/scala3-migration/incompat-type-inference.md +++ b/_overviews/scala3-migration/incompat-type-inference.md @@ -2,7 +2,7 @@ title: Type Inference type: section description: This chapter details the incompatibilities caused by the new type inference algorithm -num: 21 +num: 22 previous-page: incompat-type-checker next-page: options-intro --- diff --git a/_overviews/scala3-migration/incompatibility-table.md b/_overviews/scala3-migration/incompatibility-table.md index 8148eb7db..9fc9f8bf1 100644 --- a/_overviews/scala3-migration/incompatibility-table.md +++ b/_overviews/scala3-migration/incompatibility-table.md @@ -2,7 +2,7 @@ title: Incompatibility Table type: chapter description: This chapter list all the known incompatibilities between Scala 2.13 and Scala 3 -num: 15 +num: 16 previous-page: tooling-syntax-rewriting next-page: incompat-syntactic --- diff --git a/_overviews/scala3-migration/options-intro.md b/_overviews/scala3-migration/options-intro.md index e5a831917..9fc2d04d4 100644 --- a/_overviews/scala3-migration/options-intro.md +++ b/_overviews/scala3-migration/options-intro.md @@ -2,7 +2,7 @@ title: Compiler Options type: chapter description: This chapter shows the difference between Scala 2.13 and Scala 3 compiler options -num: 22 +num: 23 previous-page: incompat-type-inference next-page: options-lookup --- diff --git a/_overviews/scala3-migration/options-lookup.md b/_overviews/scala3-migration/options-lookup.md index a80f79c80..36db00ad8 100644 --- a/_overviews/scala3-migration/options-lookup.md +++ b/_overviews/scala3-migration/options-lookup.md @@ -2,7 +2,7 @@ title: Compiler Options Lookup Table type: section description: This section contains the compiler options lookup tables -num: 23 +num: 24 previous-page: options-intro next-page: options-new --- diff --git a/_overviews/scala3-migration/options-new.md b/_overviews/scala3-migration/options-new.md index 61fd71c0e..d101412f9 100644 --- a/_overviews/scala3-migration/options-new.md +++ b/_overviews/scala3-migration/options-new.md @@ -2,7 +2,7 @@ title: New Compiler Options type: section description: This chapter lists all the new compiler options in Scala 3 -num: 24 +num: 25 previous-page: options-lookup next-page: scaladoc-settings-compatibility --- diff --git a/_overviews/scala3-migration/plugin-intro.md b/_overviews/scala3-migration/plugin-intro.md index cd2155b62..96bfc1807 100644 --- a/_overviews/scala3-migration/plugin-intro.md +++ b/_overviews/scala3-migration/plugin-intro.md @@ -2,7 +2,7 @@ title: Compiler Plugins type: chapter description: This section shows how to migrate from using Scala 2 compiler plugins -num: 26 +num: 27 previous-page: options-new next-page: plugin-kind-projector --- diff --git a/_overviews/scala3-migration/plugin-kind-projector.md b/_overviews/scala3-migration/plugin-kind-projector.md index 471657b48..39639d128 100644 --- a/_overviews/scala3-migration/plugin-kind-projector.md +++ b/_overviews/scala3-migration/plugin-kind-projector.md @@ -2,7 +2,7 @@ title: Kind Projector Migration type: section description: This section shows how to migrate from the kind-projector plugin to Scala 3 kind-projector syntax -num: 27 +num: 28 previous-page: plugin-intro next-page: external-resources --- diff --git a/_overviews/scala3-migration/scala3-migrate.md b/_overviews/scala3-migration/scala3-migrate.md index b21ad754a..e4c66d9ac 100644 --- a/_overviews/scala3-migration/scala3-migrate.md +++ b/_overviews/scala3-migration/scala3-migrate.md @@ -2,7 +2,7 @@ title: Porting an sbt Project (using sbt-scala3-migrate) type: section description: This section shows how to use scala3-migrate to migrate a project -num: 10 +num: 11 previous-page: tutorial-prerequisites next-page: tutorial-sbt --- @@ -17,12 +17,13 @@ It consists of four sbt commands: Each one of these commands is described in details below. > #### Requirements -> - Scala 2.13, preferred 2.13.11 +> - Scala 2.13, preferred 2.13.13 > - sbt 1.5 or higher > - **Disclaimer:** This tool cannot migrate libraries containing macros. > > #### Recommendation -> Before the migration, add `-Xsource:3` to your scalac options to enable some Scala 3 syntax and behavior. +> Before the migration, add `-Xsource:3` to your scalac options to enable Scala 3 migration warnings in the Scala 2 compiler. +> See the page [Scala 2 with -Xsource:3](tooling-scala2-xsource3.html) for more details. In this tutorial, we will migrate the project in [scalacenter/scala3-migration-example](https://github.com/scalacenter/scala3-migration-example). To learn about the migration, and train yourself, you can clone this repository and follow the tutorial steps. diff --git a/_overviews/scala3-migration/scaladoc-settings-compatibility.md b/_overviews/scala3-migration/scaladoc-settings-compatibility.md index 7bb96b90d..8b1faf210 100644 --- a/_overviews/scala3-migration/scaladoc-settings-compatibility.md +++ b/_overviews/scala3-migration/scaladoc-settings-compatibility.md @@ -2,7 +2,7 @@ title: Scaladoc settings compatibility between Scala2 and Scala3 type: section description: This chapter lists all the scaladoc options for Scala 2 and Scala 3, and explains the relations between them. -num: 25 +num: 26 previous-page: options-new next-page: plugin-intro --- diff --git a/_overviews/scala3-migration/tooling-migration-mode.md b/_overviews/scala3-migration/tooling-migration-mode.md index 183edeee7..1bcc4d0b0 100644 --- a/_overviews/scala3-migration/tooling-migration-mode.md +++ b/_overviews/scala3-migration/tooling-migration-mode.md @@ -2,8 +2,8 @@ title: Scala 3 Migration Mode type: chapter description: This section describes the migration mode of the Scala 3 compiler -num: 7 -previous-page: tooling-tour +num: 8 +previous-page: tooling-scala2-xsource3 next-page: tutorial-intro --- diff --git a/_overviews/scala3-migration/tooling-scala2-xsource3.md b/_overviews/scala3-migration/tooling-scala2-xsource3.md new file mode 100644 index 000000000..7b8b98e61 --- /dev/null +++ b/_overviews/scala3-migration/tooling-scala2-xsource3.md @@ -0,0 +1,87 @@ +--- +title: Scala 2 with -Xsource:3 +type: chapter +description: This section describes the Scala 2 compiler's -Xsource:3 flag +num: 7 +previous-page: tooling-tour +next-page: tooling-migration-mode +--- + +The Scala 2.13 compiler issues helpful migration warnings with the `-Xsource:3` flag. + +Before moving to the Scala 3 compiler, it's recommended to enable this flag in Scala 2 and address the new warnings. + +There is also a variant, `-Xsource:3-cross`; see below. + +This page explains the details behind the flags. An overview is shown using `scalac -Xsource:help`. + +## Migration vs cross-building + +With Scala 2.13.13 and newer, the `-Xsource:3` flag comes in two variants: + + - `Xsource:3` enables warnings relevant for migrating a codebase to Scala 3. + In addition to new warnings, the flag enables certain benign Scala 3 syntaxes such as `import p.*`. + - `Xsource:3-cross` is useful for projects that cross-build between Scala 2 and 3 for a longer period of time. + For certain language constructs that trigger a warning with `-Xsource:3`, the behavior changes to match Scala 3. + +Details about individual warnings are listed below on this page. + +## Fatal warnings and quick fixes + +By default, Scala 3 migration warnings emitted by Scala 2.13 are fatal, i.e., they are reported as errors. +This can be changed using `-Wconf`, for example `-Wconf:cat=scala3-migration:w` changes them to be reported as warnings. +Alternatively, `-Xmigration` has the same effect. + +The [`@nowarn` annotation](https://www.scala-lang.org/api/current/scala/annotation/nowarn.html) can be used to suppress individual warnings, which also works with fatal warnings enabled. + +The Scala 2.13 compiler implements quick fixes for many Scala 3 migration warnings. +Quick fixes are displayed in Metals-based IDEs (not yet in IntelliJ), and they can be applied directly to the source code using the `-quickfix` flag, for example `-quickfix:cat=scala3-migration`. +See also `scalac -quickfix:help`. + +## Enabled Scala 3 syntax + +The `-Xsource:3` flag enables the following Scala 3 syntaxes in Scala 2: + + - `import p.*` + - `import p.m as n` + - `import p.{given, *}` + - `case C(xs*)` as an alias for `case C(xs @ _*)` + - `A & B` type intersection as an alias for `A with B` + - Selecting a method `x.f` performs an eta-expansion (`x.f _`), even without an expected type + +## Scala 3 migration warnings in detail + +Many Scala 3 migration warnings are easy to understand and identical under `-Xsource:3` and `-Xsource:3-cross`, e.g., for implicit definitions without an explicit type: + +{% highlight text %} +scala> object O { implicit val s = "" } + ^ + error: Implicit definition must have explicit type (inferred String) [quickfixable] +{% endhighlight %} + +The following table explains warnings where where the behavior changes between `-Xsource:3` and `-Xsource:3-cross`. + +| Feature | `-Xsource:3` | `-Xsource:3-cross` | +|--- |--- |--- | +| `(x: Any) + ""` is deprecated | deprecation warning | does not compile, implicit `any2stringadd` is not inferred | +| Unicode escapes in triple-quoted strings and raw interpolations (`"""\u0061"""`) | fatal warning, escape is processed | escape is not processed | +| Leading infix operators continue the previous line 1 | fatal warning, second line is a separate expression | operation continues the previous line | +| Desugaring of string interpolators using `StringContext` | fatal warning if the interpolation references a `StringContext` in scope different from `scala.StringContext` | desugaring always uses `scala.StringContext` | +| Modifiers of `apply` and `copy` methods of case classes with non-public constructors: `case class C private[p] (x: Int)` | fatal warning about the generated `apply` and `copy` being public | `apply` and `copy` inherit the access modifiers from the constructor | +| Inferred type of an overriding member 2 | fatal warning, the type of `B.f` is `String` | the type of `B.f` is `Object` | +| An implicit for type `p.A` is found in the package prefix `p` | fatal warning | the package prefix `p` is no longer part of the implicit search scope | + +Example 1: + +{% highlight text %} + def f = + 1 + + 2 +{% endhighlight %} + +Example 2: + +{% highlight text %} +trait A { def f: Object } +class B extends A { def f = "hi" } +{% endhighlight %} diff --git a/_overviews/scala3-migration/tooling-syntax-rewriting.md b/_overviews/scala3-migration/tooling-syntax-rewriting.md index e6cc2cba3..9ce122c1a 100644 --- a/_overviews/scala3-migration/tooling-syntax-rewriting.md +++ b/_overviews/scala3-migration/tooling-syntax-rewriting.md @@ -2,7 +2,7 @@ title: Scala 3 Syntax Rewriting type: chapter description: This section describes the syntax rewriting capability of the Scala 3 compiler -num: 14 +num: 15 previous-page: tutorial-macro-mixing next-page: incompatibility-table --- diff --git a/_overviews/scala3-migration/tooling-tour.md b/_overviews/scala3-migration/tooling-tour.md index 0c15849a1..5a5f1fe68 100644 --- a/_overviews/scala3-migration/tooling-tour.md +++ b/_overviews/scala3-migration/tooling-tour.md @@ -4,7 +4,7 @@ type: chapter description: This chapter is a tour of the migration tooling ecosystem num: 6 previous-page: compatibility-metaprogramming -next-page: tooling-migration-mode +next-page: tooling-scala2-xsource3 --- ## The Scala Compilers @@ -13,12 +13,10 @@ The migration has been carefully prepared beforehand in each of the two compiler ### The Scala 2.13 Compiler -The Scala 2.13 compiler supports `-Xsource:3`, an option that enables some Scala 3 syntax and behavior: -- Most deprecated syntax generates an error. -- Infix operators can start a line in the middle of a multiline expression. -- Implicit search and overload resolution follow Scala 3 handling of contravariance when checking specificity. +The Scala 2.13 compiler supports `-Xsource:3`, an option that enables migration warnings and certain Scala 3 syntax and behavior. + +The [Scala 2 with -Xsource:3](tooling-scala2-xsource3.html) page explains the flag in detail. -The `-Xsource:3` option is intended to encourage early migration. ### The Scala 3 Compiler diff --git a/_overviews/scala3-migration/tutorial-intro.md b/_overviews/scala3-migration/tutorial-intro.md index 4f207f5b9..822bfa231 100644 --- a/_overviews/scala3-migration/tutorial-intro.md +++ b/_overviews/scala3-migration/tutorial-intro.md @@ -2,7 +2,7 @@ title: Migration Tutorial type: chapter description: This chapter contains the tutorials for porting a Scala 2.13 project to Scala 3 -num: 8 +num: 9 previous-page: tooling-migration-mode next-page: tutorial-prerequisites --- diff --git a/_overviews/scala3-migration/tutorial-macro-cross-building.md b/_overviews/scala3-migration/tutorial-macro-cross-building.md index f9eec7275..b456b521a 100644 --- a/_overviews/scala3-migration/tutorial-macro-cross-building.md +++ b/_overviews/scala3-migration/tutorial-macro-cross-building.md @@ -2,7 +2,7 @@ title: Cross-Building a Macro Library type: section description: This section shows how to cross-build a macro library -num: 12 +num: 13 previous-page: tutorial-sbt next-page: tutorial-macro-mixing --- diff --git a/_overviews/scala3-migration/tutorial-macro-mixing.md b/_overviews/scala3-migration/tutorial-macro-mixing.md index 99514f637..34389b9d1 100644 --- a/_overviews/scala3-migration/tutorial-macro-mixing.md +++ b/_overviews/scala3-migration/tutorial-macro-mixing.md @@ -2,7 +2,7 @@ title: Mixing Scala 2.13 and Scala 3 Macros type: section description: This section shows how to mix Scala 2.13 and Scala 3 macros in a single artifact -num: 13 +num: 14 previous-page: tutorial-macro-mixing next-page: tooling-syntax-rewriting --- diff --git a/_overviews/scala3-migration/tutorial-prerequisites.md b/_overviews/scala3-migration/tutorial-prerequisites.md index dabb24283..426377f66 100644 --- a/_overviews/scala3-migration/tutorial-prerequisites.md +++ b/_overviews/scala3-migration/tutorial-prerequisites.md @@ -2,7 +2,7 @@ title: Prerequisites type: section description: This section details the prerequisites of migration to Scala 3 -num: 9 +num: 10 previous-page: tutorial-intro next-page: scala3-migrate --- diff --git a/_overviews/scala3-migration/tutorial-sbt.md b/_overviews/scala3-migration/tutorial-sbt.md index 78cd056d0..67d1ffed3 100644 --- a/_overviews/scala3-migration/tutorial-sbt.md +++ b/_overviews/scala3-migration/tutorial-sbt.md @@ -2,7 +2,7 @@ title: Porting an sbt Project (by hand) type: section description: This section shows how to port an sbt project -num: 11 +num: 12 previous-page: scala3-migrate next-page: tutorial-macro-cross-building ---