You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _overviews/scala3-migration/tooling-scala2-xsource3.md
+65-48
Original file line number
Diff line number
Diff line change
@@ -11,38 +11,31 @@ The Scala 2.13 compiler issues helpful migration warnings with the `-Xsource:3`
11
11
12
12
Before moving to the Scala 3 compiler, it's recommended to enable this flag in Scala 2 and address the new warnings.
13
13
14
-
There is also a variant, `-Xsource:3-cross`; see below. **Note: Enabling `-Xsource:3-cross` in Scala 2.13.13 breaks binary compatibility, follow [scala/bug#12961](https://github.com/scala/bug/issues/12961) for details.**
15
-
16
-
This page explains the details behind the flags. An overview is shown using `scalac -Xsource:help`.
14
+
Usage information is shown with `scalac -Xsource:help`.
17
15
18
16
## Migration vs cross-building
19
17
20
-
With Scala 2.13.13 and newer, the `-Xsource:3` flag comes in two variants:
18
+
With Scala 2.13.14 and newer, the `-Xsource:3` flag supports two scenarios:
21
19
22
20
-`Xsource:3` enables warnings relevant for migrating a codebase to Scala 3.
23
21
In addition to new warnings, the flag enables certain benign Scala 3 syntaxes such as `import p.*`.
24
-
-`Xsource:3-cross` is useful for projects that cross-build between Scala 2 and 3.
25
-
It is intended to reduce the maintenance burden of a cross-built project over time.
22
+
- Adding the `-Xsource-features:<features>` flag is useful to reduce the maintenance burden of projects that cross-build between Scala 2 and 3.
26
23
Certain language constructs have been backported from Scala 3 in order to improve compatibility.
27
24
Instead of warning about a behavior change in Scala 3, it adopts the new behavior.
28
-
These features can be selectively enabled using `-Xsource-features` (since 2.13.14).
29
-
30
-
Details about individual warnings are listed below on this page.
31
25
32
26
## Warnings as errors, and quick fixes
33
27
34
-
By default, Scala 3 migration warnings emitted by Scala 2.13 are reported as errors,
35
-
using the default configuration, `-Wconf:cat=scala3-migration:e`.
36
-
That ensures that migration messaging is more visible.
28
+
By default, Scala 3 migration warnings emitted by Scala 2.13 are reported as errors, using the default configuration, `-Wconf:cat=scala3-migration:e`.
29
+
This ensures that migration messaging is more visible.
37
30
Diagnostics can be emitted as warnings by specifying `-Wconf:cat=scala3-migration:w`.
38
31
Typically, emitting warnings instead of errors will cause more diagnostics to be reported.
39
32
40
33
The [`@nowarn` annotation](https://www.scala-lang.org/api/current/scala/annotation/nowarn.html) can be used in program sources to suppress individual warnings.
41
34
Diagnostics are suppressed before they are promoted to errors, so that `@nowarn` takes precedence over `-Wconf` and `-Werror`.
42
35
43
36
The Scala 2.13 compiler implements quick fixes for many Scala 3 migration warnings.
44
-
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`.
45
-
See also `scalac -quickfix:help`.
37
+
Quick fixes are displayed in Metals-based IDEs (not yet in IntelliJ), or they can be applied directly to the source code using the `-quickfix` flag, for example `-quickfix:cat=scala3-migration`.
38
+
See also `scala -quickfix:help`.
46
39
47
40
## Enabled Scala 3 syntax
48
41
@@ -57,64 +50,88 @@ The `-Xsource:3` flag enables the following Scala 3 syntaxes in Scala 2:
57
50
58
51
## Scala 3 migration warnings in detail
59
52
60
-
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:
53
+
Many Scala 3 migration warnings are easy to understand, e.g., for implicit definitions without an explicit type:
61
54
62
-
{% highlight text %}
55
+
{% highlight scala %}
63
56
scala> object O { implicit val s = "" }
64
57
^
65
58
error: Implicit definition must have explicit type (inferred String) [quickfixable]
66
59
{% endhighlight %}
67
60
68
-
The next paragraphs explain where the behavior changes between `-Xsource:3` and `-Xsource:3-cross`.
61
+
## Enabling Scala 3 features with `-Xsource-features`
69
62
70
-
### Changes affecting binary encoding
63
+
Certain Scala 3 language changes have been backported and can be enabled using `-Xsource-features`; usage and available features are shown with `-Xsource-features:help`.
71
64
72
-
As of Scala 2.13.13, there are 3 changes under `-Xsource:3-cross` that affect binary encoding of classfiles. For all of these changes a fatal warning is issued under `-Xsource:3`.
65
+
When enabling a feature, the corresponding migration warning is no longer issued.
73
66
74
-
1. The constructor modifiers of case classes (`case class C private[p] (x: Int)`) are copied to the synthetic `apply` and `copy` methods.
75
-
1. The synthetic companion objects of case classes no longer extend `FunctionN`.
76
-
1. Overriding methods without an explicit return type inherit the return type from the parent (instead of using the inferred type of the method body).
67
+
{% highlight scala %}
68
+
scala> raw"\u0061"
69
+
^
70
+
warning: Unicode escapes in raw interpolations are deprecated; use literal characters instead
71
+
val res0: String = a
77
72
78
-
For projects that are already cross-building between Scala 2 and Scala 3 with existing releases for both, enabling `-Xsource:3-cross` breaks binary compatibility. For example, if a library defines
73
+
scala> :setting -Xsource:3
79
74
80
-
{% highlight scala %}
81
-
trait A { def f: Object }
82
-
class B extends A { def f = "hi" }
83
-
{% endhighlight %}
75
+
scala> raw"\u0061"
76
+
^
77
+
error: Unicode escapes in raw interpolations are ignored in Scala 3 (or with -Xsource-features:unicode-escapes-raw); use literal characters instead
78
+
Scala 3 migration messages are errors under -Xsource:3. Use -Wconf / @nowarn to filter them or add -Xmigration to demote them to warnings.
79
+
Applicable -Wconf / @nowarn filters for this fatal warning: msg=<partofthemessage>, cat=scala3-migration, site=res1
84
80
85
-
- enabling `-Xsource:3-cross` breaks binary compatibility on Scala 2.13: existing releases have `A.f: String`, the new version will have `A.f: Object`
86
-
- adding an explicit result type `A.f: String` breaks binary compatibility on Scala 3: existing releases have `A.f: Object`
It is possible to work around this using version-dependent source files, see [scala/scala-xml#675](https://github.com/scala/scala-xml/pull/675) as an example.
83
+
scala> raw"\u0061"
84
+
val res1: String = \u0061
85
+
{% endhighlight %}
89
86
90
-
Working around the case companion `FunctionN` parent change is difficult in Scala 2.13.13.
87
+
For every such language feature, a migration warning is issued under plain `-Xsource:3`.
88
+
Enabling the feature silences the warning and adopts the changed behavior.
89
+
To avoid silent language changes when upgrading to a new Scala 2.13 version, it is recommended to enable features explicitly or use a group (e.g., `-Xsource-features:v2.13.14`).
91
90
92
-
From Scala 2.13.14, binary incompatible features can be selectively enabled under `-Xsource-features`, where the features can be enumerated.
91
+
`-Xsource:3-cross` is a shorthand for `-Xsource:3 -Xsource-features:_`.
93
92
94
93
### Changes in language semantics
95
94
96
-
The following table shows cases where `-Xsource:3-cross` adopts language feature semantics from Scala 3.
97
-
Optionally, they can be selected using `-Xsource-features`.
98
-
`-Xsource:3-cross` is a shorthand for `-Xsource:3 -Xsource-features:_`.
99
-
However, since the scope of available features may expand in future versions,
100
-
it is recommended to either specify them explicitly or fix them to the grouped features `-Xsource-features:v2.13.13` or `-Xsource-features:v2.13.14`.
95
+
The following table shows backported Scala 3 language semantics available in `-Xsource-features` / `-Xsource:3-cross`.
|Feature flag |`-Xsource:3` behavior |`-Xsource-features` /`-Xsource:3-cross` behavior|
103
98
|--- |--- |--- |
104
-
|`(x: Any) + ""` is deprecated (`any2stringadd`)| deprecation warning | does not compile, implicit `any2stringadd` is not inferred |
105
-
|Unicode escapes in triple-quoted strings and raw interpolations (`"""\u0061"""`) (`unicode-escapes-raw`) | fatal warning, escape is processed | escape is not processed |
106
-
|Leading infix operators continue the previous line <sup>1</sup> (`leading-infix`)| fatal warning, second line is a separate expression | operation continues the previous line |
107
-
|Desugaring of string interpolators using `StringContext` (`string-context-scope`)| fatal warning if the interpolation references a `StringContext` in scope different from `scala.StringContext`| desugaring always uses `scala.StringContext`|
108
-
|An implicit for type `p.A` is found in the package prefix `p` (`package-prefix-implicits`)| fatal warning | the package prefix `p` is no longer part of the implicit search scope |
109
-
|Specificity during implicit search (`implicit-resolution`) | fatal warning | use Scala-3-style downwards comparisons for implicit search and overloading resolution |
110
-
|Modifiers of synthetic methods (`case-apply-copy-access`)| fatal warning | constructor modifiers are used for apply / copy methods of case classes |
111
-
|Companions are Functions (`case-companion-function`)| fatal warning at use site | synthetic case companion objects no longer extend FunctionN, but are adapted at use site with warning |
112
-
|Override type inference (`infer-override`)| fatal warning | inferred type of member uses type of overridden member |
99
+
|`any2stringadd`: `(x: Any) + ""` is deprecated | deprecation warning | does not compile, implicit `any2stringadd` is not inferred |
100
+
|`unicode-escapes-raw`: unicode escapes in triple-quoted strings and raw interpolations (`"""\u0061"""`) | fatal warning, escape is processed | escape is not processed |
101
+
|`leading-infix`: leading infix operators continue the previous line <sup>1</sup> | fatal warning, second line is a separate expression | operation continues the previous line |
102
+
|`string-context-scope`: 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`|
103
+
|`package-prefix-implicits`: 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 |
104
+
|`implicit-resolution`: specificity during implicit search | fatal warning | use Scala-3-style [downwards comparisons](https://github.com/scala/scala/pull/6037) for implicit search and overloading resolution |
105
+
|`case-apply-copy-access`: modifiers of synthetic methods| fatal warning | constructor modifiers are used for apply / copy methods of case classes |
106
+
|`case-companion-function`: companions are Functions| fatal warning at use site | synthetic case companion objects no longer extend FunctionN, but are adapted at use site with warning |
107
+
|`infer-override`: override type inference| fatal warning | inferred type of member uses type of overridden member |
113
108
114
109
Example 1:
115
110
116
-
{% highlight text %}
111
+
{% highlight scala %}
117
112
def f =
118
113
1
119
114
+ 2
120
115
{% endhighlight %}
116
+
117
+
### Changes affecting binary encoding
118
+
119
+
As of Scala 2.13.14, there are 3 changes in `-Xsource-features` that affect binary encoding of classfiles:
120
+
121
+
1.`case-apply-copy-access`: the constructor modifiers of case classes (`case class C private[p] (x: Int)`) are copied to the synthetic `apply` and `copy` methods.
122
+
1.`case-companion-function`: the synthetic companion objects of case classes no longer extend `FunctionN`.
123
+
1.`infer-override`: overriding methods without an explicit return type inherit the return type from the parent (instead of using the inferred type of the method body).
124
+
125
+
For projects that are already cross-building between Scala 2 and 3 with existing releases for both, enabling these changes breaks binary compatibility (make sure to use [MiMa to detect such changes](https://github.com/lightbend/mima)). For example, if a library defines
126
+
127
+
{% highlight scala %}
128
+
trait A { def f: Object }
129
+
class B extends A { def f = "hi" }
130
+
{% endhighlight %}
131
+
132
+
- enabling `-Xsource-features:infer-override` breaks binary compatibility on Scala 2.13: existing releases have `A.f: String`, the new version will have `A.f: Object`
133
+
- adding an explicit result type `A.f: String` breaks binary compatibility on Scala 3: existing releases have `A.f: Object`
134
+
135
+
It is possible to work around this using version-dependent source files, see [scala/scala-xml#675](https://github.com/scala/scala-xml/pull/675) as an example.
136
+
137
+
Instead of implementing such workarounds, it might be easier not to enable changes affecting binary encoding (`-Xsource-features:v2.13.14,-case-apply-copy-access,-case-companion-function,-infer-override`).
0 commit comments