0
# Scala 3 Compiler
1

2
The Scala 3 compiler (Dotty) is a next-generation compiler for the Scala programming language featuring advanced type inference, improved metaprogramming capabilities through inline functions and macros, better error messages, and enhanced performance. It supports modern language features like union and intersection types, opaque type aliases, extension methods, and contextual abstractions.
3

4
## Package Information
5

6
- **Package Name**: scala3-compiler_3
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: Add to `build.sbt`: `libraryDependencies += "org.scala-lang" %% "scala3-compiler" % "3.7.0"`
10

11
## Core Imports
12

13
```scala
14
import dotty.tools.dotc.{Main, Driver, Compiler}
15
import dotty.tools.dotc.core.Contexts.Context
16
import dotty.tools.dotc.interfaces._
17
```
18

19
For plugin development:
20

21
```scala
22
import dotty.tools.dotc.plugins.{Plugin, StandardPlugin, PluginPhase}
23
import dotty.tools.dotc.core.Phases.Phase
24
```
25

26
For interactive/IDE usage:
27

28
```scala
29
import dotty.tools.dotc.interactive.{InteractiveDriver, InteractiveCompiler}
30
```
31

32
## Basic Usage
33

34
```scala
35
import dotty.tools.dotc.{Main, Driver}
36
import dotty.tools.dotc.interfaces.{SimpleReporter, CompilerCallback}
37

38
// Simple compilation using Main entry point
39
Main.main(Array("MyFile.scala", "-d", "output"))
40

41
// Programmatic compilation with custom settings
42
val driver = new Driver
43
val reporter = driver.process(Array("MyFile.scala", "-classpath", "lib/*"))
44

45
// Compilation with custom reporter and callback
46
val customReporter: SimpleReporter = diagnostic => 
47
  println(s"${diagnostic.level}: ${diagnostic.message}")
48

49
val callback: CompilerCallback = new CompilerCallback {
50
  override def onClassGenerated(source, generatedClass, className) = 
51
    println(s"Generated class: $className")
52
}
53

54
val result = driver.process(
55
  Array("MyFile.scala", "-d", "classes"),
56
  customReporter,
57
  callback
58
)
59
```
60

61
## Architecture
62

63
The Scala 3 compiler is built around several key components:
64

65
- **Driver System**: Entry points (`Main`, `Driver`) for different compilation modes with customizable compilation process
66
- **Compilation Pipeline**: `Compiler` class managing phases and runs with context-based execution
67
- **Phase Framework**: Extensible phase system with `MegaPhase` combining multiple mini-phases for efficiency
68
- **Plugin System**: Extensible architecture supporting both standard and research plugins
69
- **Interactive Features**: IDE integration through `InteractiveDriver` with incremental compilation support
70
- **Type System**: Advanced type system with Contexts, Types, Symbols, and Names infrastructure
71
- **AST Infrastructure**: Comprehensive abstract syntax tree system with typed and untyped variants
72

73
## Capabilities
74

75
### Core Compilation API
76

77
Primary compilation interfaces for batch compilation, programmatic usage, and build tool integration.
78

79
```scala { .api }
80
object Main extends Driver {
81
  def main(args: Array[String]): Unit
82
}
83

84
class Driver {
85
  def process(args: Array[String]): Reporter
86
  def process(args: Array[String], reporter: Reporter | Null, callback: CompilerCallback | Null): Reporter
87
  def setup(args: Array[String], rootCtx: Context): Option[(List[AbstractFile], Context)]
88
}
89

90
class Compiler {
91
  def phases: List[List[Phase]]
92
  def newRun(using Context): Run
93
  def nextRunId: Int
94
  def reset()(using Context): Unit
95
}
96
```
97

98
[Core Compilation](./core-compilation.md)
99

100
### Plugin Development API
101

102
Framework for creating compiler plugins that can extend the compilation pipeline with custom phases and transformations.
103

104
```scala { .api }
105
sealed trait Plugin {
106
  def name: String
107
  def description: String
108
  def optionsHelp: Option[String]
109
}
110

111
trait StandardPlugin extends Plugin {
112
  def initialize(options: List[String])(using Context): List[PluginPhase]
113
}
114

115
trait ResearchPlugin extends Plugin {
116
  def init(options: List[String], plan: List[List[Phase]])(using Context): List[List[Phase]]
117
}
118
```
119

120
[Plugin Development](./plugin-development.md)
121

122
### Interactive Compilation API
123

124
IDE integration capabilities providing incremental compilation, context preservation, and interactive features for development tools.
125

126
```scala { .api }
127
class InteractiveDriver extends Driver {
128
  def currentCtx: Context
129
  // Interactive compilation methods for IDE features
130
}
131

132
class InteractiveCompiler extends Compiler {
133
  // Compiler variant optimized for interactive usage
134
}
135
```
136

137
[Interactive Compilation](./interactive-compilation.md)
138

139
### Java Interfaces
140

141
External Java-compatible interfaces for tool integration and reporting, enabling seamless integration with Java-based build tools and IDEs.
142

143
```scala { .api }
144
trait SimpleReporter {
145
  def report(diag: Diagnostic): Unit
146
}
147

148
trait CompilerCallback {
149
  def onClassGenerated(source: SourceFile, generatedClass: AbstractFile, className: String): Unit = {}
150
  def onSourceCompiled(source: SourceFile): Unit = {}
151
}
152

153
trait Diagnostic {
154
  def level(): Int
155
  def message(): String
156
  def position(): Option[SourcePosition]
157
}
158
```
159

160
[Java Interfaces](./java-interfaces.md)
161

162
### Context Management
163

164
Context system providing compilation state management, phase execution control, and configuration handling throughout the compilation pipeline.
165

166
```scala { .api }
167
object Contexts {
168
  def ctx(using ctx: Context): Context
169
  def inContext[T](c: Context)(inline op: Context ?=> T): T
170
  def atPhase[T](phase: Phase)(inline op: Context ?=> T)(using Context): T
171
}
172
```
173

174
[Context Management](./context-management.md)
175

176
### REPL and Scripting
177

178
REPL (Read-Eval-Print Loop) functionality for interactive Scala development and script execution capabilities.
179

180
```scala { .api }
181
class ReplDriver {
182
  // REPL compilation and execution engine
183
}
184

185
object repl.Main {
186
  def main(args: Array[String]): Unit
187
}
188

189
class ScriptEngine extends javax.script.ScriptEngine {
190
  // JSR-223 ScriptEngine implementation
191
}
192
```
193

194
[REPL and Scripting](./repl-scripting.md)