0
# Analysis and Caching
1

2
Incremental compilation analysis, dependency tracking, and caching infrastructure for optimized build performance.
3

4
## Capabilities
5

6
### Analysis Mapping
7

8
Analysis cache facade for incremental compilation with dependency tracking.
9

10
```scala { .api }
11
case class AnalysisMap private[AnalysisMap] (
12
  analysisLocations: Map[File, FileFPrint], // Map of classpath entries to cache file fingerprints
13
  log: Logger                               // Logger for analysis operations
14
) {
15
  /**
16
   * Check if a classpath entry defines a specific class
17
   * @param classpathEntry Classpath entry to check
18
   * @return Function to test class definition
19
   */
20
  def definesClass(classpathEntry: File): String => Boolean
21
  
22
  /**
23
   * Get analysis information for a classpath entry
24
   * @param classpathEntry Classpath entry to analyze
25
   * @return Optional analysis data
26
   */
27
  def getAnalysis(classpathEntry: File): Option[Analysis]
28
}
29

30
object AnalysisMap {
31
  /**
32
   * Create AnalysisMap with file fingerprints for cache validation
33
   * @param analysisLocations Mapping of classpath entries to analysis cache file locations
34
   * @param log Logger for analysis operations
35
   * @return AnalysisMap instance with fingerprint validation
36
   */
37
  def create(analysisLocations: Map[File, File], log: Logger): AnalysisMap
38
  
39
  /**
40
   * Create analysis store for cache file management
41
   * @param cacheFile Analysis cache file location
42
   * @return AnalysisStore for reading/writing analysis data
43
   */
44
  def cachedStore(cacheFile: File): AnalysisStore
45
}
46
```
47

48
### File Fingerprinting
49

50
File fingerprint management for cache invalidation and dependency tracking.
51

52
```scala { .api }
53
class FileFPrint(val file: File, val fprint: String)
54

55
object FileFPrint {
56
  /**
57
   * Generate file fingerprint for cache validation
58
   * @param file File to fingerprint
59
   * @return Optional file fingerprint (None if file doesn't exist)
60
   */
61
  def fprint(file: File): Option[FileFPrint]
62
}
63
```
64

65
### Cache Utilities
66

67
LRU cache implementation with soft references for memory-efficient caching.
68

69
```scala { .api }
70
object Cache {
71
  /**
72
   * Create LRU cache with soft references
73
   * @param maxSize Maximum cache size
74
   * @return Cache instance with specified size limit
75
   */
76
  def apply[K <: AnyRef, V <: AnyRef](maxSize: Int): gcache.Cache[K, V]
77
}
78

79
// Implicit extensions for cache operations
80
implicit class CacheExtensions[K <: AnyRef, V <: AnyRef](cache: gcache.Cache[K, V]) {
81
  /**
82
   * Get value from cache or compute and store if absent
83
   * @param key Cache key
84
   * @param value Value computation function
85
   * @return Cached or computed value
86
   */
87
  def getOrElseUpdate(key: K)(value: => V): V
88
  
89
  /**
90
   * Get all cache entries as sequence
91
   * @return Sequence of key-value pairs
92
   */
93
  def entries: Seq[(K, V)]
94
}
95
```
96

97
## Usage Examples
98

99
### Basic Analysis Mapping
100

101
```scala
102
import org.pantsbuild.zinc._
103
import org.pantsbuild.zinc.cache._
104
import java.io.File
105

106
// Create analysis mapping for dependency tracking
107
val analysisLocations = Map(
108
  new File("/path/to/upstream.jar") -> new File("/path/to/upstream-analysis.cache"),
109
  new File("/path/to/library.jar") -> new File("/path/to/library-analysis.cache")
110
)
111

112
val log = Loggers.create(Level.Info, color = true)
113
val analysisMap = AnalysisMap.create(analysisLocations, log)
114

115
// Check if a jar defines a specific class
116
val definesMyClass = analysisMap.definesClass(new File("/path/to/upstream.jar"))
117
val hasMyClass = definesMyClass("com.example.MyClass")
118

119
// Get analysis data for incremental compilation
120
val upstreamAnalysis = analysisMap.getAnalysis(new File("/path/to/upstream.jar"))
121
```
122

123
### File Fingerprinting
124

125
```scala
126
import org.pantsbuild.zinc.FileFPrint
127
import java.io.File
128

129
// Generate fingerprints for cache validation
130
val sourceFile = new File("src/main/scala/Example.scala")
131
val fingerprint = FileFPrint.fprint(sourceFile)
132

133
fingerprint match {
134
  case Some(fp) => 
135
    println(s"File: ${fp.file}, Fingerprint: ${fp.fprint}")
136
  case None => 
137
    println("File does not exist or cannot be read")
138
}
139
```
140

141
### Cache Management
142

143
```scala
144
import org.pantsbuild.zinc.cache.Cache
145
import java.io.File
146

147
// Create LRU cache for compiler instances
148
val compilerCache = Cache[String, AnyRef](maxSize = 10)
149

150
// Cache operations with automatic computation
151
val cachedValue = compilerCache.getOrElseUpdate("scala-2.12.17") {
152
  // Expensive compiler creation operation
153
  createCompilerInstance("2.12.17")
154
}
155

156
// View all cached entries
157
val allEntries = compilerCache.entries
158
println(s"Cache contains ${allEntries.size} entries")
159
```
160

161
### Integration with Compilation
162

163
```scala
164
import org.pantsbuild.zinc._
165
import java.io.File
166

167
// Set up analysis mapping for incremental compilation
168
val settings = Settings.parse(args.toSeq).get
169
val inputs = Inputs(log, settings)
170

171
// Analysis mapping is automatically created from settings
172
val analysisMap = inputs.analysisMap
173

174
// Use in compilation process
175
val compiler = Compiler(Setup(settings), log)
176
compiler.compile(inputs, Some(new File(".")), reporter, progress)(log)
177

178
// Analysis data is automatically cached and reused for subsequent compilations
179
```
180

181
## Advanced Configuration
182

183
### Analysis Options
184

185
Configuration options specific to analysis and caching behavior.
186

187
```scala { .api }
188
case class AnalysisOptions(
189
  cache: Option[File],              // Analysis cache file location
190
  cacheMap: Map[File, File]         // Mapping of dependency analysis locations
191
)
192
```
193

194
### Performance Tuning
195

196
The analysis and caching system provides several performance optimization features:
197

198
- **Incremental Analysis**: Tracks API changes and recompiles only affected sources
199
- **Dependency Tracking**: Maintains precise dependency graphs for minimal recompilation
200
- **File Fingerprinting**: Uses content hashes to detect actual changes vs. timestamp updates
201
- **Memory Management**: Uses soft references in caches to prevent memory leaks
202
- **Transactional Updates**: Ensures analysis consistency even if compilation fails
203

204
## Error Handling
205

206
Analysis operations handle various error conditions gracefully:
207

208
- Missing analysis files are treated as empty analysis
209
- Corrupted cache files trigger full recompilation
210
- File access errors are logged and compilation continues
211
- Invalid fingerprints trigger cache invalidation