0
# Core Compilation API
1

2
Primary compilation interfaces providing batch compilation capabilities, programmatic usage patterns, and build tool integration for the Scala 3 compiler.
3

4
## Capabilities
5

6
### Main Entry Point
7

8
Main class providing command-line compilation interface with standard argument processing.
9

10
```scala { .api }
11
/**
12
 * Main entry point for the Scala 3 compiler
13
 * Extends Driver with default settings for command-line usage
14
 */
15
object Main extends Driver {
16
  /**
17
   * Command-line entry point for batch compilation
18
   * @param args Array of command-line arguments including source files and options
19
   */
20
  def main(args: Array[String]): Unit
21
}
22
```
23

24
**Usage Examples:**
25

26
```scala
27
// Command-line style compilation
28
dotty.tools.dotc.Main.main(Array(
29
  "src/main/scala/MyClass.scala",
30
  "-d", "target/classes",
31
  "-classpath", "lib/dependency.jar"
32
))
33

34
// With compiler flags
35
dotty.tools.dotc.Main.main(Array(
36
  "src/main/scala/MyClass.scala",
37
  "-Xfatal-warnings",
38
  "-feature",
39
  "-deprecation"
40
))
41
```
42

43
### Driver Class
44

45
Core compiler driver providing customizable compilation process with multiple entry points for different use cases.
46

47
```scala { .api }
48
/**
49
 * Core compiler driver with customizable compilation process
50
 * Provides multiple entry points for different integration scenarios
51
 */
52
class Driver {
53
  /**
54
   * Simple compilation entry point with default reporter
55
   * @param args Array of compilation arguments
56
   * @return Reporter containing compilation results and diagnostics
57
   */
58
  def process(args: Array[String]): Reporter
59
  
60
  /**
61
   * Principal compilation entry point with custom reporter and callback
62
   * @param args Array of compilation arguments
63
   * @param reporter Custom reporter for handling diagnostics (null for default)
64
   * @param callback Custom callback for compilation events (null for no callback)
65
   * @return Reporter containing compilation results and diagnostics
66
   */
67
  def process(args: Array[String], reporter: Reporter | Null, callback: CompilerCallback | Null): Reporter
68
  
69
  /**
70
   * Java reflection-friendly entry point using SimpleReporter interface
71
   * @param args Array of compilation arguments
72
   * @param simple SimpleReporter implementation for Java interop
73
   * @param callback CompilerCallback for compilation events
74
   * @return ReporterResult with compilation outcome
75
   */
76
  def process(args: Array[String], simple: SimpleReporter | Null, callback: CompilerCallback | Null): ReporterResult
77
  
78
  /**
79
   * Setup compilation context from command-line arguments
80
   * @param args Array of compilation arguments
81
   * @param rootCtx Root compilation context
82
   * @return Option containing source files and configured context, or None if setup failed
83
   */
84
  def setup(args: Array[String], rootCtx: Context): Option[(List[AbstractFile], Context)]
85
}
86
```
87

88
**Usage Examples:**
89

90
```scala
91
import dotty.tools.dotc.Driver
92
import dotty.tools.dotc.interfaces.{SimpleReporter, CompilerCallback}
93

94
val driver = new Driver
95

96
// Simple compilation
97
val reporter = driver.process(Array("MyFile.scala", "-d", "output"))
98
if (reporter.hasErrors) {
99
  println("Compilation failed")
100
}
101

102
// With custom reporter
103
val customReporter = new SimpleReporter {
104
  override def report(diagnostic: Diagnostic): Unit = {
105
    println(s"[${diagnostic.level}] ${diagnostic.message}")
106
  }
107
}
108

109
val callback = new CompilerCallback {
110
  override def onClassGenerated(source, generatedClass, className) = {
111
    println(s"Generated: $className")
112
  }
113
}
114

115
val result = driver.process(
116
  Array("MyFile.scala", "-classpath", "lib/*"),
117
  customReporter,
118
  callback
119
)
120
```
121

122
### Compiler Class
123

124
Central compiler class managing compilation phases, runs, and overall compilation orchestration.
125

126
```scala { .api }
127
/**
128
 * Central class managing compilation phases and runs
129
 * Coordinates the entire compilation pipeline
130
 */
131
class Compiler {
132
  /**
133
   * Complete list of compilation phases organized by phase groups
134
   * Each inner list represents phases that can run in parallel
135
   * @return Nested list of Phase objects representing the compilation pipeline
136
   */
137
  def phases: List[List[Phase]]
138
  
139
  /**
140
   * Create a new compilation run within the given context
141
   * @param ctx Compilation context
142
   * @return New Run instance for processing source files
143
   */
144
  def newRun(using Context): Run
145
  
146
  /**
147
   * Generate unique run identifier for tracking compilation runs
148
   * @return Unique integer identifier for the next compilation run
149
   */
150
  def nextRunId: Int
151
  
152
  /**
153
   * Reset compiler state for clean compilation
154
   * Clears caches and resets internal state
155
   * @param ctx Compilation context
156
   */
157
  def reset()(using Context): Unit
158
}
159
```
160

161
### Run Class
162

163
Represents a single compilation run responsible for processing source files through the compilation pipeline.
164

165
```scala { .api }
166
/**
167
 * Represents a single compilation run with file processing
168
 * Manages the execution of compilation phases on a set of source files
169
 */
170
class Run {
171
  /**
172
   * Compile the given source files
173
   * @param files List of source files to compile
174
   */
175
  def compile(files: List[AbstractFile])(using Context): Unit
176
  
177
  /**
178
   * Get the unique identifier for this compilation run
179
   * @return Integer run ID
180
   */
181
  def runId: Int
182
  
183
  /**
184
   * Check if this compilation run produced any errors
185
   * @return True if errors were reported during compilation
186
   */
187
  def hasErrors: Boolean
188
}
189
```
190

191
### CompilationUnit Class
192

193
Represents a single source file being compiled with associated metadata and compilation state.
194

195
```scala { .api }
196
/**
197
 * Represents a single source file being compiled
198
 * Contains source content, parsing results, and compilation metadata
199
 */
200
class CompilationUnit {
201
  /**
202
   * The source file being compiled
203
   */
204
  def source: SourceFile
205
  
206
  /**
207
   * The abstract syntax tree for this compilation unit
208
   */
209
  def untpdTree: Tree[?]
210
  
211
  /**
212
   * The typed abstract syntax tree (available after typing phase)
213
   */
214
  def tpdTree: Tree[?]
215
}
216
```
217

218
**Usage Examples:**
219

220
```scala
221
import dotty.tools.dotc.{Compiler, Driver}
222
import dotty.tools.dotc.core.Contexts._
223

224
// Custom compiler usage
225
class MyCompiler extends Compiler {
226
  override def phases = 
227
    List(List(/* custom phases */)) ++ super.phases
228
}
229

230
val driver = new Driver {
231
  override def newCompiler(using Context) = new MyCompiler
232
}
233

234
// Using compiler directly
235
given Context = initContext()
236
val compiler = new Compiler
237
val run = compiler.newRun
238
// run.compile(sourceFiles)
239
```
240

241
## Types
242

243
### AbstractFile
244

245
```scala { .api }
246
/**
247
 * Abstract representation of a file or directory
248
 * Used throughout the compiler for source files and output locations
249
 */
250
abstract class AbstractFile {
251
  def name: String
252
  def path: String
253
  def isDirectory: Boolean
254
  def exists: Boolean
255
}
256
```
257

258
### SourceFile
259

260
```scala { .api }
261
/**
262
 * Represents a source file with content and metadata
263
 */
264
class SourceFile {
265
  def file: AbstractFile
266
  def content: Array[Char]
267
  def lineIndices: Array[Int]
268
}
269
```
270

271
### Reporter
272

273
```scala { .api }
274
/**
275
 * Base class for compilation reporting
276
 * Handles diagnostics, errors, and warnings during compilation
277
 */
278
abstract class Reporter {
279
  def hasErrors: Boolean
280
  def hasWarnings: Boolean
281
  def errorCount: Int
282
  def warningCount: Int
283
}
284
```