CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-pantsbuild--zinc

Zinc is a standalone version of sbt's incremental compiler meant to be run in nailgun.

Pending
Overview
Eval results
Files

logging-reporting.mddocs/

Logging and Reporting

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

Capabilities

Logger Factory

Factory methods for creating loggers with various output configurations.

object Loggers {
  /**
   * Create composite logger with console and optional file output
   * @param level Logging level (Debug, Info, Warn, Error)
   * @param color Enable colored console output
   * @param out Console output destination (default: system out)
   * @param captureLog Optional file for capturing log output
   * @return Logger instance with specified configuration
   */
  def create(level: Level.Value, color: Boolean, 
             out: ConsoleOut = ConsoleOut.systemOut, 
             captureLog: Option[File] = None): Logger
}

Reporter Factory

Factory for creating reporters with filtering capabilities for compilation messages.

object Reporters {
  /**
   * Create filtered reporter for compilation messages
   * @param log Underlying logger for message output
   * @param fileFilters Regex patterns to filter warnings by file path
   * @param msgFilters Regex patterns to filter warnings by message content
   * @param maximumErrors Maximum number of errors before stopping (default: 100)
   * @return Reporter with specified filtering configuration
   */
  def create(log: Logger, fileFilters: Seq[Regex], msgFilters: Seq[Regex], 
             maximumErrors: Int = 100): Reporter
}

Regex Filter Reporter

Reporter implementation that filters compilation warnings using regex patterns.

class RegexFilterReporter(
  fileFilters: Seq[Regex],          // File path filter patterns
  msgFilters: Seq[Regex],           // Message content filter patterns
  maximumErrors: Int,               // Maximum error count
  log: Logger                       // Underlying logger
) extends Reporter {
  /**
   * Log compilation message with filtering
   * @param pos Source position information
   * @param msg Compilation message
   * @param sev Message severity level
   */
  def log(pos: xsbti.Position, msg: String, sev: xsbti.Severity): Unit
  
  /**
   * Report compilation problem with filtering
   * @param problem Compilation problem details
   */
  def report(problem: xsbti.Problem): Unit
  
  /**
   * Check if any errors have been reported
   * @return True if errors were reported
   */
  def hasErrors: Boolean
  
  /**
   * Check if any warnings have been reported
   * @return True if warnings were reported
   */
  def hasWarnings: Boolean
  
  /**
   * Get problems reported during compilation
   * @return Array of reported problems
   */
  def problems: Array[xsbti.Problem]
  
  /**
   * Reset reporter state
   */
  def reset(): Unit
}

Progress Reporting

Simple compilation progress implementation with phase logging and heartbeat monitoring.

class SimpleCompileProgress(
  logPhases: Boolean,               // Log compilation phases
  printProgress: Boolean,           // Print progress percentage
  heartbeatSecs: Int                // Heartbeat interval in seconds
)(log: Logger) extends xsbti.compile.CompileProgress {
  
  /**
   * Report start of compilation phase for a source unit
   * @param phase Compilation phase name
   * @param unitPath Path to source unit being compiled
   */
  def startUnit(phase: String, unitPath: String): Unit
  
  /**
   * Report compilation progress and handle heartbeat
   * @param current Current number of completed units
   * @param total Total number of units to compile
   * @return True to continue compilation, false to cancel
   */
  def advance(current: Int, total: Int): Boolean
}

Usage Examples

Basic Logging Setup

import org.pantsbuild.zinc.logging._
import org.pantsbuild.zinc.Level
import java.io.File

// Create console logger with colored output
val log = Loggers.create(
  level = Level.Info,
  color = true
)

// Create logger with file capture
val logWithFile = Loggers.create(
  level = Level.Debug,
  color = false,
  captureLog = Some(new File("compilation.log"))
)

// Use logger
log.info("Starting compilation...")
log.warn("Deprecated API usage detected")
log.error("Compilation failed")

Reporter with Filtering

import org.pantsbuild.zinc.logging._
import java.util.regex.Pattern
import scala.util.matching.Regex

// Create reporter with warning filters
val fileFilters = Seq(
  ".*generated.*".r,              // Filter warnings from generated files
  ".*test.*".r                    // Filter warnings from test files
)

val msgFilters = Seq(
  ".*deprecated.*".r,             // Filter deprecation warnings
  ".*unused import.*".r           // Filter unused import warnings
)

val reporter = Reporters.create(
  log = log,
  fileFilters = fileFilters,
  msgFilters = msgFilters,
  maximumErrors = 50
)

// Use reporter in compilation
compiler.compile(inputs, cwd, reporter, progress)(log)

// Check compilation results
if (reporter.hasErrors) {
  println("Compilation failed with errors")
  reporter.problems.foreach(problem => log.error(problem.message))
}

Progress Reporting

import org.pantsbuild.zinc._

// Create progress reporter
val progress = new SimpleCompileProgress(
  logPhases = true,                // Log each compilation phase
  printProgress = true,            // Print percentage progress  
  heartbeatSecs = 30               // Heartbeat every 30 seconds
)(log)

// Use in compilation
compiler.compile(inputs, cwd, reporter, progress)(log)

Advanced Reporter Configuration

import org.pantsbuild.zinc.logging._

// Create custom regex filter reporter
val customReporter = new RegexFilterReporter(
  fileFilters = Seq(
    ".*/target/.*".r,              // Exclude build output directories
    ".*/\\..*".r                   // Exclude hidden files
  ),
  msgFilters = Seq(
    ".*warning.*not exhaustive.*".r  // Filter specific warning types
  ),
  maximumErrors = 25,
  log = log
)

// Monitor compilation progress
compiler.compile(inputs, cwd, customReporter, progress)(log)

// Detailed result analysis
println(s"Compilation completed:")
println(s"  Errors: ${customReporter.hasErrors}")
println(s"  Warnings: ${customReporter.hasWarnings}")
println(s"  Total problems: ${customReporter.problems.length}")

// Reset for next compilation
customReporter.reset()

Configuration Integration

Console Options

The logging system integrates with the configuration system through ConsoleOptions:

case class ConsoleOptions(
  logLevel: Level.Value,            // Logging level
  color: Boolean,                   // Colored output
  logPhases: Boolean,               // Log compilation phases
  printProgress: Boolean,           // Print progress
  heartbeatSecs: Int,               // Heartbeat interval
  fileFilters: Seq[Regex],          // File filters for warnings
  msgFilters: Seq[Regex]            // Message filters for warnings
)

Integration with Settings

import org.pantsbuild.zinc._

// Parse settings with logging configuration
val settings = Settings.parse(args.toSeq).get

// Extract console options
val consoleOpts = settings.consoleLog

// Create logger from settings
val log = Loggers.create(
  level = consoleOpts.logLevel,
  color = consoleOpts.color,
  captureLog = settings.captureLog
)

// Create reporter from settings  
val reporter = Reporters.create(
  log = log,
  fileFilters = consoleOpts.fileFilters,
  msgFilters = consoleOpts.msgFilters
)

// Create progress from settings
val progress = new SimpleCompileProgress(
  logPhases = consoleOpts.logPhases,
  printProgress = consoleOpts.printProgress,
  heartbeatSecs = consoleOpts.heartbeatSecs
)(log)

Types

// Logging levels
object Level extends Enumeration {
  val Debug, Info, Warn, Error = Value
}

// Console output destinations
sealed trait ConsoleOut
object ConsoleOut {
  case object SystemOut extends ConsoleOut
  case object SystemErr extends ConsoleOut
}

Install with Tessl CLI

npx tessl i tessl/maven-org-pantsbuild--zinc

docs

analysis-caching.md

compiler-management.md

configuration.md

index.md

logging-reporting.md

main-entry.md

utilities.md

tile.json