Add reference docs for forward compatibility feature #2301
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
julienrf
reviewed
Jan 31, 2022
There was a problem hiding this comment.
Thank you @prolativ for the update of documentation.
The page binary-compatibility contains useful information, but I think it would be good to summarize somewhere what are the relevant action points for library maintainers, with a concrete example.
| ``` | ||
|
|
||
| Language imports supersede command-line settings in the source files where they are specified. Only one language import specifying a source version is allowed in a source file, and it must come before any definitions in that file. | ||
| Additional information on interoperability and migration between Scala 2 and 3 can be found [here](https://docs.scala-lang.org/scala3/guides/migration/compatibility-intro.html). |
There was a problem hiding this comment.
Please use the {% link ... %} directives to create internal links.
|
|
||
| In Scala 2 different minor versions of the compiler were free to change the way how they encode different language features in JVM bytecode so each bump of the compiler's minor version resulted in breaking binary compatibility and if a project had any Scala dependencies they all needed to be (cross-)compiled to the same minor Scala version that was used in that project itself. On the contrary, Scala 3 has a stable encoding into JVM bytecode. | ||
|
|
||
| In addition to classfiles the compilation process in Scala 3 also produces files with `.tasty` extension. The [TASTy](https://docs.scala-lang.org/scala3/guides/tasty-overview.html) format is an intermediate representation of Scala code containing full information about sources together with information provided by the typer. Some of this information is lost during generation of bytecode so Scala 3 compilers read TASTy files during compilation in addition to classfiles to know the exact types of values, methods, etc. in already compiled classes (although compilation from TASTy files only is also possible). TASTy files are also typically distributed together with classfiles in published artifacts. |
There was a problem hiding this comment.
Maybe introduce the wording “fully elaborated Scala programs”? TASTy contains fully elaborated Scala programs in the sense that it contains all the information (context parameters and type parameters) that have been inferred by the compiler during the compilation.
Comment on lines
+33
to
+34
| scalaOrganization.value %% "scala3-library" % scalaVersion.value, | ||
| scalaOrganization.value %% "scala3-library_sjs1" % scalaVersion.value // for Scala.js projects |
There was a problem hiding this comment.
Would this work?
Suggested change
| scalaOrganization.value %% "scala3-library" % scalaVersion.value, | |
| scalaOrganization.value %% "scala3-library_sjs1" % scalaVersion.value // for Scala.js projects | |
| scalaOrganization.value %% "scala3-library" % scalaVersion.value, | |
| scalaOrganization.value %%% "scala3-library" % scalaVersion.value // for Scala.js projects |
There was a problem hiding this comment.
I tried this but for some reason this didn't seem to work
| E.g. when a project gets compiled with Scala compiler `3.x1.y1` and `-Yscala-release 3.x2` option and then published using sbt | ||
| then the standard library in version `3.x1.y1` gets added to the project's dependencies instead of `3.x2.y2`. | ||
| When the dependencies are added to the classpath during compilation with Scala `3.x2.y2` the compiler will crash while trying to read TASTy files in the newer format. | ||
| A currently known workaround is to modify the build definition of the dependent project by explicitly overriding the version of Scala standard library in dependencies, e.g. |
There was a problem hiding this comment.
Is there a known workaround that could be applied on the library itself, instead of the modules that depend on the library? Maybe a way to override the package task in sbt to override the version of the dependency to scala3-library? Maybe @eed3si9n knows a trick?
prolativ
force-pushed
the
add-forward-compat-docs
branch
from
966adbd
to
ee3eb6d
Compare
|
We can add more documentation later when we set some best practices how to make this work smoothly. For now it's still experimental but hopefully we should get some support for this feature in build tools. |
julienrf
reviewed
Jan 31, 2022
|
|
||
| In Scala 2, different minor versions of the compiler were free to change the way how they encoded different language features in JVM bytecode. So each bump of the compiler's minor version resulted in breaking the binary compatibility, and if a project had any Scala dependencies they all needed to be (cross-)compiled to the same minor Scala version that was used in that project itself. On the contrary, Scala 3 has a stable encoding into JVM bytecode. | ||
|
|
||
| In addition to classfiles the compilation process in Scala 3 also produces files with `.tasty` extension. [TASTy]({% link scala3/guides/tasty-overview.md %}) files are an intermediate representation of Scala programs containing fully elaborated Scala code in the sense that they contain all the information that have been inferred by the compiler during the compilation (like contextual parameters and type parameters). Some of this information is lost during generation of bytecode so Scala 3 compilers read TASTy files during compilation in addition to classfiles to know the exact types of values, methods, etc. in already compiled classes (although compilation from TASTy files only is also possible). TASTy files are also typically distributed together with classfiles in published artifacts. |
There was a problem hiding this comment.
Sorry to be picky, but:
Suggested change
| In addition to classfiles the compilation process in Scala 3 also produces files with `.tasty` extension. [TASTy]({% link scala3/guides/tasty-overview.md %}) files are an intermediate representation of Scala programs containing fully elaborated Scala code in the sense that they contain all the information that have been inferred by the compiler during the compilation (like contextual parameters and type parameters). Some of this information is lost during generation of bytecode so Scala 3 compilers read TASTy files during compilation in addition to classfiles to know the exact types of values, methods, etc. in already compiled classes (although compilation from TASTy files only is also possible). TASTy files are also typically distributed together with classfiles in published artifacts. | |
| In addition to classfiles, the compilation process in Scala 3 also produces files with `.tasty` extension. [TASTy]({% link scala3/guides/tasty-overview.md %}) files represent fully elaborated Scala programs in the sense that they contain all the information that has been inferred by the compiler during the compilation (like contextual parameters and type parameters). Some of this information is lost during the generation of bytecode so Scala 3 compilers read TASTy files during compilation in addition to classfiles to know the exact types of values, methods, etc. in already compiled classes (although compilation from TASTy files only is also possible). TASTy files are also typically distributed together with classfiles in published artifacts. |
julienrf
approved these changes
Jan 31, 2022
prolativ
force-pushed
the
add-forward-compat-docs
branch
from
ee3eb6d
to
58968f2
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adapted from scala/scala3#14156