0
# Zinc Incremental Compiler
1

2
Zinc is a standalone version of sbt's incremental compiler designed to run efficiently in Nailgun server environments. It provides advanced incremental compilation for Scala projects with support for mixed Java/Scala compilation, analysis caching, and comprehensive build system integration.
3

4
## Package Information
5

6
- **Package Name**: org.pantsbuild:zinc
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `"org.pantsbuild" % "zinc" % "1.0.12"`
10

11
## Core Imports
12

13
```scala
14
import org.pantsbuild.zinc.{Main, Compiler, Settings, Inputs, Setup}
15
import org.pantsbuild.zinc.logging.{Loggers, Reporters}
16
```
17

18
For Java interoperability:
19

20
```java
21
import org.pantsbuild.zinc.Main;
22
import org.pantsbuild.zinc.Compiler;
23
import org.pantsbuild.zinc.Settings;
24
```
25

26
## Basic Usage
27

28
```scala
29
import org.pantsbuild.zinc._
30
import org.pantsbuild.zinc.logging._
31
import sbt.Level
32
import java.io.File
33

34
// Command-line compilation
35
val args = Array(
36
  "-scala-home", "/path/to/scala",
37
  "-classpath", "/path/to/dependencies",
38
  "-d", "/path/to/output",
39
  "src/main/scala/Example.scala"
40
)
41
Main.run(args, Some(new File(".")))
42

43
// Programmatic compilation
44
val Parsed(settings, _, errors) = Settings.parse(args.toSeq)
45
if (errors.nonEmpty) throw new RuntimeException(s"Parse errors: ${errors.mkString(", ")}")
46

47
val log = Loggers.create(Level.Info, color = true)
48
val setup = Setup(settings)
49
val inputs = Inputs(log, settings)
50
val compiler = Compiler(setup, log)
51
val reporter = Reporters.create(log, Seq.empty, Seq.empty)
52
val progress = new SimpleCompileProgress(logPhases = false, printProgress = true, heartbeatSecs = 0)(log)
53

54
compiler.compile(inputs, Some(new File(".")), reporter, progress)(log)
55
```
56

57
## Architecture
58

59
Zinc is built around several key components:
60

61
- **Main Entry Point**: Command-line interface and compilation orchestration (`Main` object)
62
- **Compiler Management**: Core compilation logic with caching and incremental analysis (`Compiler`)
63
- **Configuration System**: Comprehensive settings and input management (`Settings`, `Inputs`, `Setup`)
64
- **Analysis Engine**: Incremental compilation analysis and caching (`AnalysisMap`, dependency tracking)
65
- **Logging Framework**: Flexible logging and progress reporting with filtering capabilities
66
- **Option Parsing**: Complete command-line argument processing framework
67
- **Java Integration**: Full Java compiler support with mixed compilation capabilities
68

69
## Capabilities
70

71
### Main Entry Point
72

73
Primary command-line interface and programmatic entry points for Zinc compilation.
74

75
```scala { .api }
76
object Main {
77
  def main(args: Array[String]): Unit
78
  def run(args: Array[String], cwd: Option[File]): Unit
79
}
80
```
81

82
[Main Entry Point](./main-entry.md)
83

84
### Compiler Management
85

86
Core compiler creation, caching, and incremental compilation execution.
87

88
```scala { .api }
89
object Compiler {
90
  def apply(setup: Setup, log: Logger): Compiler
91
  def getOrCreate(setup: Setup, log: Logger): Compiler
92
  def create(setup: Setup, log: Logger): Compiler
93
}
94

95
class Compiler {
96
  def compile(inputs: Inputs, cwd: Option[File], reporter: xsbti.Reporter, 
97
              progress: xsbti.compile.CompileProgress)(log: Logger): Unit
98
}
99
```
100

101
[Compiler Management](./compiler-management.md)
102

103
### Configuration System
104

105
Comprehensive configuration management including command-line parsing, compilation settings, and input specification.
106

107
```scala { .api }
108
case class Settings(
109
  help: Boolean,
110
  version: Boolean,
111
  consoleLog: ConsoleOptions,
112
  sources: Seq[File],
113
  classpath: Seq[File],
114
  classesDirectory: File,
115
  scala: ScalaLocation,
116
  scalacOptions: Seq[String],
117
  // ... additional fields
118
)
119

120
object Settings {
121
  def parse(args: Seq[String]): Parsed[Settings]
122
  def normalise(settings: Settings, cwd: Option[File]): Settings
123
}
124
```
125

126
[Configuration System](./configuration.md)
127

128
### Analysis and Caching
129

130
Incremental compilation analysis, dependency tracking, and caching infrastructure.
131

132
```scala { .api }
133
case class AnalysisMap(getPCMapping: Map[File, File], definesClassLookup: File => String => Boolean) {
134
  def definesClass(classpathEntry: File): String => Boolean
135
  def getAnalysis(classpathEntry: File): Option[Analysis]
136
}
137

138
object AnalysisMap {
139
  def create(analysisLocations: Map[File, File], log: Logger): AnalysisMap
140
}
141
```
142

143
[Analysis and Caching](./analysis-caching.md)
144

145
### Logging and Reporting
146

147
Flexible logging framework with filtering, progress reporting, and console output management.
148

149
```scala { .api }
150
object Loggers {
151
  def create(level: Level.Value, color: Boolean, 
152
             out: ConsoleOut = ConsoleOut.systemOut, 
153
             captureLog: Option[File] = None): Logger
154
}
155

156
object Reporters {
157
  def create(log: Logger, fileFilters: Seq[Regex], msgFilters: Seq[Regex], 
158
             maximumErrors: Int = 100): Reporter
159
}
160
```
161

162
[Logging and Reporting](./logging-reporting.md)
163

164
### Utility Functions
165

166
Comprehensive utility functions for file operations, timing, property management, and debugging.
167

168
```scala { .api }
169
object Util {
170
  def timing(start: Long): String
171
  def normalise(cwd: Option[File])(file: File): File
172
  def checkWritable(file: File): Boolean
173
  def setProperties(props: Seq[String]): Unit
174
}
175
```
176

177
[Utility Functions](./utilities.md)