0
# Configuration System
1

2
Comprehensive configuration management including command-line parsing, compilation settings, and input specification.
3

4
## Capabilities
5

6
### Settings Management
7

8
Main configuration class containing all compilation options and command-line argument parsing.
9

10
```scala { .api }
11
case class Settings(
12
  help: Boolean,                    // Show help flag
13
  version: Boolean,                 // Show version flag
14
  consoleLog: ConsoleOptions,       // Console logging configuration
15
  captureLog: Option[File],         // Optional log capture file
16
  sources: Seq[File],               // Source files to compile
17
  classpath: Seq[File],             // Compilation classpath
18
  classesDirectory: File,           // Output directory for compiled classes
19
  scala: ScalaLocation,             // Scala compiler location configuration
20
  scalacOptions: Seq[String],       // Scala compiler options
21
  javaHome: Option[File],           // Java home directory
22
  forkJava: Boolean,                // Fork Java compiler flag
23
  javaOnly: Boolean,                // Java-only compilation flag
24
  javacOptions: Seq[String],        // Java compiler options
25
  compileOrder: CompileOrder,       // Compilation order strategy
26
  sbt: SbtJars,                     // SBT jar locations
27
  incOptions: IncOptions,           // Incremental compilation options
28
  analysis: AnalysisOptions,        // Analysis configuration
29
  properties: Seq[String]           // JVM system properties
30
)
31

32
object Settings {
33
  /**
34
   * Parse command-line arguments into Settings
35
   * @param args Command-line argument sequence
36
   * @return Parsed settings or error information
37
   */
38
  def parse(args: Seq[String]): Parsed[Settings]
39
  
40
  /**
41
   * Print usage information to console
42
   */
43
  def printUsage(): Unit
44
  
45
  /**
46
   * Normalize file paths relative to working directory
47
   * @param settings Settings to normalize
48
   * @param cwd Optional working directory
49
   * @return Settings with normalized paths
50
   */
51
  def normalise(settings: Settings, cwd: Option[File]): Settings
52
  
53
  /**
54
   * Convert string to CompileOrder enumeration
55
   * @param order Order string ("Mixed", "JavaThenScala", "ScalaThenJava")
56
   * @return CompileOrder enumeration value
57
   */
58
  def compileOrder(order: String): CompileOrder
59
  
60
  /**
61
   * Check if string is command-line option flag
62
   * @param s String to check
63
   * @return True if string starts with option prefix
64
   */
65
  def isOpt(s: String): Boolean
66
}
67
```
68

69
### Console Configuration
70

71
Console logging and output configuration options.
72

73
```scala { .api }
74
case class ConsoleOptions(
75
  logLevel: Level.Value,            // Logging level (Debug/Info/Warn/Error)
76
  color: Boolean,                   // Enable colored output
77
  logPhases: Boolean,               // Log compilation phases
78
  printProgress: Boolean,           // Print compilation progress
79
  heartbeatSecs: Int,               // Heartbeat interval in seconds
80
  fileFilters: Seq[Regex],          // File name filters for warnings
81
  msgFilters: Seq[Regex]            // Message filters for warnings
82
)
83
```
84

85
### Scala Location Configuration
86

87
Scala compiler location and jar specification.
88

89
```scala { .api }
90
case class ScalaLocation(
91
  home: Option[File],               // Scala home directory
92
  path: Seq[File],                  // Direct path to Scala jars
93
  compiler: Option[File],           // Scala compiler jar file
94
  library: Option[File],            // Scala library jar file
95
  extra: Seq[File]                  // Additional Scala jars
96
)
97

98
object ScalaLocation {
99
  /**
100
   * Java API constructor for ScalaLocation
101
   * @param home Scala home directory
102
   * @param path Direct path to Scala jars
103
   * @param compiler Scala compiler jar
104
   * @param library Scala library jar
105
   * @param extra Additional Scala jars
106
   * @return ScalaLocation instance
107
   */
108
  def create(home: File, path: JList[File], compiler: File, 
109
             library: File, extra: JList[File]): ScalaLocation
110
  
111
  /**
112
   * Create ScalaLocation from Scala home directory
113
   * @param home Scala installation directory
114
   * @return ScalaLocation with auto-detected jars
115
   */
116
  def fromHome(home: File): ScalaLocation
117
  
118
  /**
119
   * Create ScalaLocation from explicit jar paths
120
   * @param path List of Scala jar files
121
   * @return ScalaLocation with specified jars
122
   */
123
  def fromPath(path: JList[File]): ScalaLocation
124
}
125
```
126

127
### SBT Integration Configuration
128

129
Configuration for SBT jar locations required for Zinc compilation.
130

131
```scala { .api }
132
case class SbtJars(
133
  sbtInterface: Option[File] = None,         // SBT interface jar location
134
  compilerInterfaceSrc: Option[File] = None  // Compiler interface source location
135
)
136
```
137

138
### Analysis Options
139

140
Analysis cache configuration for incremental compilation.
141

142
```scala { .api }
143
case class AnalysisOptions(
144
  cache: Option[File],              // Analysis cache file location
145
  cacheMap: Map[File, File]         // Mapping of dependency analysis locations
146
)
147
```
148

149
### Incremental Compilation Options
150

151
Configuration for incremental compilation behavior and optimization.
152

153
```scala { .api }
154
case class IncOptions(
155
  transitiveStep: Int,              // Steps before transitive closure
156
  recompileAllFraction: Double,     // Fraction limit before recompiling all
157
  relationsDebug: Boolean,          // Enable relations debug logging
158
  apiDebug: Boolean,                // Enable API debug logging
159
  apiDiffContextSize: Int,          // API diff context size
160
  apiDumpDirectory: Option[File],   // Directory for API dumps
161
  transactional: Boolean,           // Enable transactional compilation
162
  backup: Option[File],             // Backup directory for transactional mode
163
  recompileOnMacroDef: Boolean,     // Recompile dependencies on macro definition
164
  nameHashing: Boolean              // Enable name hashing algorithm
165
) {
166
  /**
167
   * Convert to SBT IncOptions for compatibility
168
   * @return SBT IncOptions instance
169
   */
170
  def options: sbt.inc.IncOptions
171
  
172
  /**
173
   * Get classfile manager for incremental compilation
174
   * @return Function creating ClassfileManager
175
   */
176
  def classfileManager: () => ClassfileManager
177
}
178
```
179

180
### Compilation Inputs
181

182
Complete specification of all inputs required for a compilation run.
183

184
```scala { .api }
185
case class Inputs(
186
  classpath: Seq[File],             // Compilation classpath
187
  sources: Seq[File],               // Source files to compile
188
  classesDirectory: File,           // Output directory for classes
189
  scalacOptions: Seq[String],       // Scala compiler options
190
  javacOptions: Seq[String],        // Java compiler options
191
  cacheFile: File,                  // Analysis cache file
192
  analysisMap: AnalysisMap,         // Analysis mapping for dependencies
193
  javaOnly: Boolean,                // Java-only compilation flag
194
  compileOrder: CompileOrder,       // Compilation order strategy
195
  incOptions: IncOptions            // Incremental compilation options
196
)
197

198
object Inputs {
199
  /**
200
   * Create Inputs from Settings configuration
201
   * @param log Logger for input processing
202
   * @param settings Settings containing compilation configuration
203
   * @return Inputs instance ready for compilation
204
   */
205
  def apply(log: Logger, settings: Settings): Inputs
206
  
207
  /**
208
   * Java API constructor for Inputs
209
   * @param log Logger instance
210
   * @param classpath Compilation classpath
211
   * @param sources Source files to compile
212
   * @param classesDirectory Output directory
213
   * @param scalacOptions Scala compiler options
214
   * @param javacOptions Java compiler options
215
   * @param analysisCache Analysis cache file
216
   * @param analysisMap Analysis mapping
217
   * @param compileOrder Compilation order string
218
   * @param incOptions Incremental compilation options
219
   * @return Inputs instance
220
   */
221
  def create(log: Logger, classpath: JList[File], sources: JList[File],
222
             classesDirectory: File, scalacOptions: JList[String],
223
             javacOptions: JList[String], analysisCache: File,
224
             analysisMap: JMap[File, File], compileOrder: String,
225
             incOptions: IncOptions): Inputs
226
  
227
  /**
228
   * Verify and normalize input configuration
229
   * @param inputs Inputs to verify
230
   * @return Verified and normalized inputs
231
   */
232
  def verify(inputs: Inputs): Inputs
233
  
234
  /**
235
   * Get default cache file location
236
   * @param classesDir Output classes directory
237
   * @return Default cache file location
238
   */
239
  def defaultCacheLocation(classesDir: File): File
240
  
241
  /**
242
   * Debug display of inputs configuration
243
   * @param inputs Inputs to display
244
   * @param output Output function for display
245
   */
246
  def show(inputs: Inputs, output: String => Unit): Unit
247
}
248
```
249

250
### Compiler Setup
251

252
Compiler identity and jar configuration for compilation environment setup.
253

254
```scala { .api }
255
case class Setup(
256
  scalaCompiler: File,              // Scala compiler jar
257
  scalaLibrary: File,               // Scala library jar
258
  scalaExtra: Seq[File],            // Additional Scala jars
259
  sbtInterface: File,               // SBT interface jar
260
  compilerInterfaceSrc: File,       // Compiler interface sources
261
  javaHome: Option[File],           // Java home directory
262
  forkJava: Boolean,                // Fork Java compiler flag
263
  cacheDir: File                    // Cache directory
264
)
265

266
object Setup {
267
  /**
268
   * Create Setup from Settings configuration
269
   * @param settings Settings containing setup information
270
   * @return Setup instance ready for compiler creation
271
   */
272
  def apply(settings: Settings): Setup
273
  
274
  /**
275
   * Verify setup configuration is valid
276
   * @param setup Setup to verify
277
   * @param log Logger for verification messages
278
   * @return True if setup is valid
279
   */
280
  def verify(setup: Setup, log: Logger): Boolean
281
  
282
  /**
283
   * Print Zinc version information
284
   */
285
  def printVersion(): Unit
286
  
287
  /**
288
   * Get Zinc cache directory location
289
   * @return Cache directory file
290
   */
291
  def zincCacheDir: File
292
  
293
  /**
294
   * Format version string for display
295
   * @return Formatted version string
296
   */
297
  def versionString: String
298
}
299
```
300

301
## Usage Examples
302

303
```scala
304
import org.pantsbuild.zinc._
305
import java.io.File
306

307
// Parse command-line arguments
308
val args = Seq(
309
  "-scala-home", "/usr/local/scala",
310
  "-classpath", "/path/to/deps",
311
  "-d", "/output",
312
  "Example.scala"
313
)
314

315
val Parsed(settings, remaining, errors) = Settings.parse(args)
316
if (errors.nonEmpty) {
317
  throw new IllegalArgumentException(s"Parse errors: ${errors.mkString(", ")}")
318
}
319

320
// Create setup and inputs
321
val setup = Setup(settings)
322
val inputs = Inputs(log, settings)
323

324
// Use for compilation...
325
```
326

327
## Types
328

329
```scala { .api }
330
// Compilation order strategies
331
sealed trait CompileOrder
332
case object Mixed extends CompileOrder
333
case object JavaThenScala extends CompileOrder  
334
case object ScalaThenJava extends CompileOrder
335

336
// Command-line parsing results
337
case class Parsed[Context](
338
  context: Context,                 // Parsed configuration object
339
  remaining: Seq[String],           // Remaining unparsed arguments
340
  errors: Seq[String] = Seq.empty   // Any parsing errors encountered
341
)
342
```