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
+45-50
Original file line number
Diff line number
Diff line change
@@ -11,29 +11,22 @@ 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
@@ -57,59 +50,39 @@ 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
55
{% highlight text %}
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`.
69
-
70
-
### Changes affecting binary encoding
71
-
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`.
73
-
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).
77
-
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
79
-
80
-
{% highlight scala %}
81
-
trait A { def f: Object }
82
-
class B extends A { def f = "hi" }
83
-
{% endhighlight %}
84
-
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`
61
+
## Enabling Scala 3 features with `-Xsource-features`
87
62
88
-
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.
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`.
89
64
90
-
Working around the case companion `FunctionN` parent change is difficult in Scala 2.13.13.
65
+
For every such language feature, a migration warning is issued under plain `-Xsource:3`.
66
+
Enabling the feature silences the warning and adopts the changed behavior.
67
+
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
68
92
-
From Scala 2.13.14, binary incompatible features can be selectively enabled under `-Xsource-features`, where the features can be enumerated.
69
+
`-Xsource:3-cross` is a shorthand for `-Xsource:3 -Xsource-features:_`.
93
70
94
71
### Changes in language semantics
95
72
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`.
73
+
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
76
|--- |--- |--- |
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 |
77
+
|`any2stringadd`: `(x: Any) + ""` is deprecated | deprecation warning | does not compile, implicit `any2stringadd` is not inferred |
78
+
|`unicode-escapes-raw`: unicode escapes in triple-quoted strings and raw interpolations (`"""\u0061"""`) | fatal warning, escape is processed | escape is not processed |
79
+
|`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 |
80
+
|`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`|
81
+
|`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 |
82
+
|`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 |
83
+
|`case-apply-copy-access`: modifiers of synthetic methods| fatal warning | constructor modifiers are used for apply / copy methods of case classes |
84
+
|`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 |
85
+
|`infer-override`: override type inference| fatal warning | inferred type of member uses type of overridden member |
113
86
114
87
Example 1:
115
88
@@ -118,3 +91,25 @@ Example 1:
118
91
1
119
92
+ 2
120
93
{% endhighlight %}
94
+
95
+
### Changes affecting binary encoding
96
+
97
+
As of Scala 2.13.14, there are 3 changes in `-Xsource-features` that affect binary encoding of classfiles:
98
+
99
+
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.
100
+
1.`case-companion-function`: the synthetic companion objects of case classes no longer extend `FunctionN`.
101
+
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).
102
+
103
+
For projects that are already cross-building between Scala 2 and Scala 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
104
+
105
+
{% highlight scala %}
106
+
trait A { def f: Object }
107
+
class B extends A { def f = "hi" }
108
+
{% endhighlight %}
109
+
110
+
- 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`
111
+
- adding an explicit result type `A.f: String` breaks binary compatibility on Scala 3: existing releases have `A.f: Object`
112
+
113
+
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.
114
+
115
+
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