Scala 3 migration guide
This repository is a continuously evolving guide to support the migration to Scala 3. As a member of the community you are encouraged to participate the effort by sharing your migrating experience.
Since the announcement that Dotty will eventually become Scala 3, the Dotty contributors and the SIP committee is taking great care of the migration accessibility for everyone (library maintainer, application owner, and people teaching others).
A number of complementary initiatives are being undertaken to ease the migration. This repository is not a replacement of those initiatives. Its purpose is to gather knowledge, to collect feedback and to encourage the collaboration. The ultimate goal being to drive the effort of the community toward the release of Scala 3.
All information you may want to know before starting the migration of your codebase should be available in this guide. If not you may want to contribute.
Introduction
What is Scala 3?
Dotty is the project name of the new compiler and improved language that will become Scala 3.
The compiler has been completely redesigned, which means that the typechecker and type inferencer are totally new. In the corner cases they may not behave as in the scala 2 compiler. The implicit resolution rules have been cleaned up as well.
The language itself has been improved. The changes compared to Scala 2 are limited to:
- some simplified and restricted constructs for safety or consistency reasons
- some dropped features
- and also some exciting new features
Last but not least, the macros system from Scala 2 has been dropped and replaced by a new macro system that is safer, more robust and that breaks the compiler dependency. The downside of it, in terms of migration, is that all the macro usages must be re-written. Chances are that you don't use macros in your codebase, but you depend on libraries that define macro methods.
For a complete overview of the changes in Dotty compared to Scala 2, please visit the Dotty website.
What is left unchanged?
There are reasons to say that Scala 3 is just another Scala version:
- A large subset of the Scala 2 language still compiles to Scala 3.
- The standard library api and implementation are unchanged.
- The ABI (Application Binary Interface) is unchanged. The bytecode and the IR of scala-js and scala-native, produced by the Scala 2 and Dotty compilers are the same. It enables interoperability and gradual migration, and it relieves us from surprising behavior at runtime.
A Tour of the Migration Tools
The Dotty compiler
The Dotty compiler itself is a powerful migration tool.
You can use dotc on your Scala 2 source code with the -source 3.0-migration option. It will do its best to compile most of your code and it will issue a warning for each incompatibility. For a detailed explanation of the dotc -source option see #5700.
Even more than that, in combination with the -rewrite flag, the Dotty compiler is able to rewrite some of the Scala 2 code.
Leveraging this tool, the community has already migrated a significant number of well-known libraries, forming the community build.
The description of these rules are being documented here. If you find any missing rule that is straightforward to implement, please create an issue in the Dotty repository.
In case the rule is not trivial to implement you may fall back to the Scalafix tool.
Scalafix
Scalafix may be the complementary tool to assist the compiler for non-trivial incompatibilities.
In particular, it might be very convenient for automatic or semi-automatic resolution of the type inference and implicit resolution incompatibilities, by explicitly writting down the types and implicit values.
Such Scalafix rules could be hosted by the scala-rewrites repository. Contributors Welcome!
sbt and other build tools
The sbt build tool does already support Dotty and cross-compilation with Scala 2. It is able to glue all the migration tools together to provide the best migration experience.
Other build tools may also support Dotty and cross-compilation with Scala 2. Contributors Welcome!
Metals and other IDEs
Visual Studio Code has its own Dotty Language Server plugin that you can simply configure by running the sbt launchIDE task of the sbt-dotty plugin.
The Dotty support in Metals is on its way, stay tuned to #1367.
The latest Scala plugin for Intellij Idea already have preliminary support for Scala 3.
Scaladex
Scala 3 is backward compatible with the Scala 2.13 libraries with the exception of libraries that use macros. If you depend on one of those libraries you may want to check in Scaladex, the Scala library index, if this dependency has already been ported to Dotty.
Content
The /docs folder in this repository contains:
- dotty-rewrites.md: A list of the dotty rewrite rules.
- cross-build.md: A tutorial for cross building your codebase. This is something that library maintainers would be interested in.
- upgrade.md: Applications do not require cross building. You can jump straight and upgrade them to Scala 3 by following this tutorial.
- macros.md: General knowledge about migrating macros.
The structure of this repository is not fully defined yet.
In the near future it may be added:
- A status of the migration related issues that have been submitted to the dotty project or to another migration related project. As well as a list of the on-going initiatives to help the migration.
- A corpus of source code examples that don't cross-compile and how they should translate from scala 2.13 to Dotty.