Migrating from Scala 2

Besides the warnings, the option accepts these Scala 3 forms on Scala 2.13, so that code that uses them still compiles on both: import p.*, import p.m as n, import p.{given, *}, the pattern case C(xs*) as an alias for case C(xs @ _*), and A & B as an alias for A with B.

Under -Xsource-features (or the shorthand -Xsource:3-cross, which stands for -Xsource:3 -Xsource-features:_) the compiler does not warn about a changed behavior but adopts it. These are the behaviors, as listed in the guide for 2.13.18 and not run here individually:

To avoid silent language changes when moving to a newer 2.13.x, enable features explicitly or by a version group, such as -Xsource-features:v2.13.14. Three of the features change the bytecode (case-apply-copy-access, case-companion-function and infer-override). For a library that already publishes both a 2.13 and a 3 artifact, enabling them breaks binary compatibility, so the guide recommends leaving those three out (-Xsource-features:v2.13.14,-case-apply-copy-access,-case-companion-function,-infer-override) and checking with MiMa; the library authors' side of that story is in Versions, Compatibility & JDKs.

The infer-override row is the one most likely to bite an application, and it shows what the quick fixes protect. With a parent that declares def grade: Object and a child that writes def grade = "II", Scala 2 infers String for the child, while Scala 3 infers Object, and a caller that wrote val g: String = new Alpine().grade stops compiling. In the sbt project used later on this page, -Xsource:3 reported it as

and -quickfix rewrote the definition to def grade: String = "II", which means the same in both languages.

Source: Scala 3 Migration Guide: Scala 2 with -Xsource:3

Add it to project/plugins.sbt, with sbt 1.x in project/build.properties (here sbt.version=1.13.0):

Source: Scala 3 Migration Guide: Porting an sbt Project (using sbt-scala3-migrate)

From then on every sbt start prints a reminder with the four commands, which goes away when the plugin is removed:

If the build has several modules, start with the one that has the fewest dependencies, because Scala 2.13 and Scala 3 modules can depend on each other in either order. The command argument must not be an aggregate project.

migrateDependencies main checks every library and compiler plugin against Scala 3 and sorts them into groups. The output for the build above, as run:

Each group asks for a different action:

The updated dependency section, which still builds on 2.13:

Source: Scala 3 Migration Guide: Porting an sbt Project (using sbt-scala3-migrate)

Reload, check that it compiles and tests pass on 2.13, and commit.

The Scala 3 compiler has a different set of options. migrateScalacOptions main sorts the current ones:

Some options listed may come from sbt or from another sbt plugin rather than from your build file; keep those plugins current and they adapt themselves. The build then keeps one list per compiler, again so that it still compiles on 2.13:

Source: Scala 3 Migration Guide: Porting an sbt Project (using sbt-scala3-migrate)

Two values differ from what the plugin printed. The plugin suggested -Xunchecked-java-output-version:8, and Scala 3.9.0 rejected it later in this run with "8 is not a valid choice for -Xunchecked-java-output-version", because Scala 3.8 and newer need JDK 17 or later. And -Ykind-projector is now -Xkind-projector, as noted above. The full old-to-new mapping is on the guide’s options lookup page, Compiler Options Lookup Table.

migrateSyntax main runs Scalafix rules that patch syntax. The rules are ProcedureSyntax, fix.scala213.ExplicitNullaryEtaExpansion, migrate.ParensAroundLambda, fix.scala213.ExplicitNonNullaryApply, fix.scala213.Any2StringAdd and ExplicitResultTypes. In this project the earlier -quickfix pass had already removed the procedure syntax and the lambda without parentheses, so what remained was the auto-application:

Some incompatibilities are not covered by the rules. They are rare and easy to fix by hand with the help of the table in Incompatibilities & Dropped Features. Review the patches, run the tests and commit.

The Scala 3 type inference differs in details, so some inferred types now cause errors. migrateTypes main finds them by compiling with Scala 3, adds the type ascriptions that make the code compile, and re-checks. Here, with the previous steps done, it found nothing left to patch and recommended a version:

Notice the version: the plugin recommends a Scala 3.3 release, not a newer line. The recommendation says that the code compiles with the migration compiler; the version to use in the build is your choice, as discussed at the top of this page. The guide’s own run of the command, on a project with more type problems, listed the candidate patches it found and applied only the ones that were needed.

For one module, set scalaVersion to the target. For several modules, repeat from step 2 on the next one. When all modules are done, remove sbt-scala3-migrate from project/plugins.sbt together with the Scala 2.13 settings. The next section shows the cross-building setup, which is a good way to keep both compilers available while the switch is verified.

Source: Scala 3 Migration Guide: Porting an sbt Project (using sbt-scala3-migrate)

Source: Scala 3 Migration Guide: Porting an sbt Project (by hand)

The default version is the first one in scalaVersion; the command ++2.13.18 switches the current session to the other, and reload always returns to the default. On the migrated project, both compilers ran the same tests (the commands were passed to sbt in batch mode, shown here as in the shell, with the output shortened):

A version that is not listed in crossScalaVersions is not selected by plain `: with `3.10.0, sbt 1.13.0 reported "Setting Scala version to 3.9.0", the listed Scala 3 entry. To try the newest compiler anyway, force it with the ! suffix and a space, ++ 3.10.0!. The same project, cleaned and run that way, compiled with Scala 3.10.0 and passed its two tests with the same output.

The first Scala 3 compile of the project failed twice, and both failures are the option problems described in step 3: -Ykind-projector printed "Option -Ykind-projector is deprecated: Use -Xkind-projector instead" and -Xunchecked-java-output-version:8 was rejected. They are worth remembering because both options come straight out of the migration plugin and the guide.

If you did not use the plugin, compile on Scala 3 will report unresolved dependencies, because the declared versions are not published for Scala 3. For each one either upgrade to a version that is, or use the 2.13 artifact:

Source: Scala 3 Migration Guide: Porting an sbt Project (by hand)

Make the same change in every module of the build, and check on Scala 2.13 that nothing broke. The opposite direction, using a Scala 3 library from Scala 2.13, is CrossVersion.for2_13Use3 and is limited; see the compatibility page. These lines are quoted from the guide and were not run here.

The guide suggests a common list, a Scala 2.13 list and a Scala 3 list, with the migration mode switched on for Scala 3 and fatal warnings disabled during the migration so that the automatic rewrites can complete:

Source: Scala 3 Migration Guide: Porting an sbt Project (by hand)

(Quoted from the guide, not run as one block.) On a recent Scala 3 compiler -Xfatal-warnings is a deprecated alias: the compiler prints "Option -Xfatal-warnings is a deprecated alias: use -Werror instead", and -Werror is the current name.

Compile with Scala 3. The compiler produces two kinds of diagnostics. Migration warnings are fixed automatically at the end; errors must be fixed by hand, using the table in Incompatibilities & Dropped Features. After each fix, run the tests on Scala 2.13 again, and prefer fixes that preserve binary compatibility, which matters most for a published library. Macro incompatibilities are the exception: they cannot be patched, because the macro code must be rewritten from scratch (see below).

Once the errors are gone, only migration warnings remain. Rewrite them by compiling once more with -rewrite, as in step 2, then remove -source:3.0-migration and put -Xfatal-warnings back. In sbt that is a temporary setting:

(The guide’s session, quoted.) Keep in mind what step 2 showed: one -source level reports only what is removed up to that level, so a project that uses constructs removed in 3.4 needs a second pass at -source:3.4-migration.

Run the tests on both versions and set the continuous integration pipeline up for Scala 3. Tests are the only guarantee against the rare case in which a different implicit value is chosen and changes the behavior. Then drop the 2.13 entry from crossScalaVersions if you do not publish for Scala 2, or keep it if the library supports both. A library that publishes both artifacts should check compatibility with MiMa and read Versions, Compatibility & JDKs first.

Source: Scala 3 Migration Guide: Porting an sbt Project (by hand)

The Scala 2 variant is the original macro, and it needs scala-reflect on its class path:

Source: Cross-Building a Macro Library, Mixing Scala 2.13 and Scala 3 Macros

The Scala 3 variant must have the same signature, and is written with quotes and splices:

Source: Cross-Building a Macro Library, Mixing Scala 2.13 and Scala 3 Macros

Note the + 1: the Scala 3 position API counts lines from zero, while enclosingPosition.line of Scala 2 starts at one. (The guide’s Scala 3 version records the full source path with pos.sourceFile.path.toString; this version stores only the file name, which is why its output below differs from the Scala 2 one.)

In an sbt build, the shared class stays in src/main/scala, and the files that only one compiler can read go to src/main/scala-2 and src/main/scala-3, a version-specific directory convention that sbt provides by default. The guide’s final layout is:

(The sbt layout is quoted from the guide; the sources were compiled with Scala CLI.) Compiling each variant into its own JAR and calling the macro from an application, the Scala 3 application printed the file and line:

Source: Cross-Building a Macro Library, Mixing Scala 2.13 and Scala 3 Macros

and the Scala 2.13.18 application, which has the same call on line 5, printed the full path that its macro records:

The two artifacts are separate: the Scala 3 application given the Scala 2 JAR gets the error shown under prerequisites. Cross-validate with a test that runs on both compilers, as the guide does with a single MUnit test that asserts the line number; this protects against the two implementations drifting apart.

The alternative is a single artifact built with Scala 3. The Scala 3 compiler can read Scala 2 definitions, and a Scala 2.13 compiler with the TASTy reader can read Scala 3 definitions, so one object can define the same method twice, once as a Scala 2 macro and once as a Scala 3 inline macro. Each compiler picks the definition it understands. Because the Scala 3 compiler can compile a Scala 2 macro implementation only when it contains no quasiquotes or reification, the Scala 2 implementation usually lives in a small Scala 2.13 module that the main module depends on. That module also has to own the Location class, which is why the guide says it "had to be moved downstream":

Source: Cross-Building a Macro Library, Mixing Scala 2.13 and Scala 3 Macros

The Scala 3 module (compiled with the compat module’s JAR on the class path) defines both:

Source: Cross-Building a Macro Library, Mixing Scala 2.13 and Scala 3 Macros

location is not an overloaded method: the compiler recognizes the first definition as Scala 2 only and the second as Scala 3 only. Two details were found by running it, and neither is mentioned in the guide’s listing:

Built with 3.3.8 and with 3.10.0, both mixed libraries expanded correctly in a Scala 3.10.0 application, which printed Location(Main.scala,4). A Scala 2.13.18 application with the same call then used the library through the TASTy reader. Without the option, the compiler stops and tells you what to add:

With -Ytasty-reader, the application compiled against the library built by 3.10.0 and printed the Scala 2 macro’s output, Location(.../app2/Main.scala,5). Against the library built by 3.3.8 it first failed with "could not find package scala.annotation.internal whilst reading annotation of package location", until org.scala-lang:scala3-library_3:3.3.8 was added to the class path; then it printed the same result. In a published artifact the dependency would normally come in transitively; the guide’s instructions for a consumer are:

(The consumer snippet is the guide’s, not run.) The 3.10.0 result is not a sign that mixing works with recent compilers. The limit is the one from the compatibility page: Scala 2.13’s -Ytasty-reader supports Scala 3 libraries built by 3.7 or older, and from 3.8 on it is unsupported. Re-run with 2.13.18, a small library with a case class and an object compiled and ran when it was built by 3.7.4, and failed to compile when it was built by 3.8.3, 3.9.0 or 3.10.0, even with scala3-library_3 of the same version on the class path ("could not find package scala.annotation.internal", or scala.deriving for 3.10.0). Since 3.8 the Scala 3 standard library is published as org.scala-lang:scala-library 3.x, and the 2.13.18 scala-library takes its place. Only a library whose API needs nothing from that standard library, such as this macro library, still got through. A library that mixes macros for 2.13 users is therefore built by 3.7 or older (3.3 LTS is the usual choice), and it has to be tested the same way, with a consumer on each side. Which of the two options to choose follows from the audience: cross-building gives each user an ordinary artifact at the price of two implementations to publish, while mixing publishes once but depends on the reader. The tests of the guide’s mixing tutorial live in a separate cross-built module on top (example-test, with -Ytasty-reader added when the Scala version is 2.13), because the tests have to run under both compilers.

Source: Cross-Building a Macro Library, Mixing Scala 2.13 and Scala 3 Macros