A brief ‘TASTy for End Users’ page, per Anatolii’s request

Author: alvinj

_overviews/scala3-book/tasty-for-end-users.md

@@ -0,0 +1,150 @@
+If you create a Scala 3 source code file named _Hello.scala_:
+
+```scala
+@main def hello = println("Hello, world")
+```
+
+and then compile that file with `scalac`:
+
+```bash
+$ scalac Hello.scala
+```
+
+you’ll notice that amongst other resulting files, `scalac` creates files with the _.tasty_ extension:
+
+```bash
+$ ls -1
+Hello$package$.class
+Hello$package.class
+Hello$package.tasty
+Hello.scala
+hello.class
+hello.tasty
+```
+
+This leads to the natural question, “What is tasty?”
+
+
+
+## What is TASTy?
+
+TASTy is an acronym that comes from the term, _Typed Abstract Syntax Trees_.
+It’s a high-level interchange format for Scala 3, and in this document we’ll refer to it as _Tasty_.
+
+A first important thing to know is that Tasty files are generated by the `scalac` compiler, and contain _all_ of the information about your source code, including the syntactic structure of your program, and _complete_ information about types, positions, and even documentation. Tasty files contain much more information than _.class_ files, which are generated to run on the JVM. (More on this shortly.)
+
+In Scala 3, the compilation process looks like this:
+
+```
+         ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+$ scalac │ Pizza.scala │ ──> │ Pizza.tasty │ ──> │ Pizza.class │
+         └─────────────┘     └─────────────┘     └─────────────┘
+                ▲                   ▲                   ▲      
+                │                   │                   │      
+                                                               
+           Your source          TASTy file          Class file  
+               code             for scalac         for the JVM  
+                                (contains          (incomplete  
+                                 complete          information)
+                               information)
+```
+
+### The issue with _.class_ files
+
+Because of issues such as type erasure, _.class_ files are actually an incomplete representation of your code. A simple way to demonstrate this is with a `List` example.
+
+_Type erasure_ means that when you write Scala code like this that’s supposed to run on the JVM:
+
+```scala
+val xs: List[Int] = List(1, 2, 3)
+```
+
+that code is compiled to a _.class_ file that needs to be compatible with the JVM. As a result of that compatibility requirement, the code inside that class file --- which you can see with a `javap` command --- ends up looking like this:
+
+```java
+public scala.collection.immutable.List<java.lang.Object> xs();
+```
+
+That `javap` command output shows a Java representation of what’s contained in the class file. Notice in this output that `xs` _is not_ defined as a `List[Int]` any more; it’s essentially represented as a `List[java.lang.Object]`. For your Scala code to work with the JVM, the `Int` type has been erased.
+
+Later, when you access an element of your `List[Int]` in your Scala code, like this:
+
+```scala
+val x = xs(0)
+```
+
+the resulting class file will have a casting operation for this line of code, which you can think of being like this:
+
+```
+int x = (Int) xs.get(0)               // Java-ish
+val x = xs.get(0).asInstanceOf[Int]   // more Scala-like
+```
+
+Again, this is done for compatibility, so your Scala code can run on the JVM.
+
+And this discussion only covers the topic of type erasure. There are similar issues for every other Scala construct that the JVM isn’t aware of, including constructs like unions, intersections, traits with parameters, and many more Scala 3 features.
+
+
+### Key points
+
+So that’s the first takeaway from this section: The types you specify in your Scala code aren’t represented completely accurately in _.class_ files.
+
+A second key point is to understand that there are differences between the information that’s available at _compile time_ and _run time_:
+
+- At **compile time**, as `scalac` reads and analyzes your code, it knows that `xs` is a `List[Int]`
+- When the compiler writes your code to a class file, it writes that `xs` is a `List[Object]`, and it adds casting information everywhere else `xs` is accessed
+- Then at **run time** --- with your code running inside the JVM --- the JVM doesn’t know that your list is a `List[Int]`
+
+With Scala 3 and Tasty, here’s another important note about compile time:
+
+- When you write Scala 3 code that uses other Scala 3 libraries, `scalac` doesn’t have to read their _.class_ files any more; it can read their _.tasty_ files, which, as mentioned, are an _exact_ representation of your code. This helps in many ways.
+
+{% comment %}
+NOTE: In regards to the previous paragraphs, I’ve read that there’s also metadata in the class files, but I don’t know those details.
+{% endcomment %}
+
+
+
+## Tasty benefits
+
+As you can imagine, having a complete representation of your code in a platform-neutral form has many benefits:
+
+{% comment %}
+TODO: These lines mostly come from https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html, and I don’t know exactly what the first bullet point means:
+{% endcomment %}
+
+- The compiler uses it to support separate compilation.
+- The Scala _Language Server Protocol_-based language server uses it to support hyperlinking, command completion, documentation, and also for global operations such as find-references and renaming.
+- Tasty makes an excellent foundation for a new generation of reflection-based macros.
+- A build tool can use it to cross-build on different platforms and migrate code from one binary version to another.
+- Optimizers and analyzers can use it for deep code analysis and advanced code generation.
+
+There’s one more big benefit:
+
+- Because the Scala 2.13.4 compiler can read Tasty files, and the Scala 3 compiler can read Scala 2.13 class files, you can intermix Scala 3 and Scala 2.13 code in the same project.
+
+
+
+## More information
+
+In summary, Tasty is a high-level interchange format for Scala 3, and _.tasty_ files contain a complete representation of your source code, leading to the benefits outlined in the previous section.
+
+For more details, see these resources:
+
+- In this [this video](https://www.youtube.com/watch?v=YQmVrUdx8TU), Jamie Thompson of the Scala Center provides a thorough discussion of how Tasty works, and its benefits
+- [Binary Compatibility for library authors][binary] discusses binary compatibility, source compatibility, and the JVM execution model
+- [Forward Compatibility for the Scala 3 Transition](https://www.scala-lang.org/blog/2020/11/19/scala-3-forward-compat.html) demonstrates techniques for using Scala 2.13 and Scala 3 in the same project
+
+These articles provide more information about Scala 3 macros:
+
+- [Scala Macro Libraries](https://scalacenter.github.io/scala-3-migration-guide/docs/macros/macro-libraries.html)
+- [Macros: The Plan for Scala 3](https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html)
+- [The reference documentation on TASTy Reflect][tasty-reflect]
+- [The reference documentation on macros](macros)
+
+
+
+[binary]: {% link _overviews/core/binary-compatibility-for-library-authors.md %}
+[tasty-reflect]: {{ site.scala3ref }}/metaprogramming/tasty-reflect.html
+[macros]: {{ site.scala3ref }}/metaprogramming/macros.html
+