Documentation
¶
Overview ¶
Package runtime provides the CLI-facing runtime support shared across ninjago commands: flag and argument parsing, logging, console and status rendering, memory-mapped file I/O, and the RunParameters bag that ties them together.
Index ¶
- Constants
- func Get[T any](ctx context.Context, key ContextKey) T
- type CliFlags
- type CloseFunc
- type Console
- func (c *Console) BuildFinished()
- func (c *Console) BuildStarted()
- func (c *Console) BuildStepCanceled(id int)
- func (c *Console) BuildStepFinished(id int, exitCode int, output string)
- func (c *Console) BuildStepStarted(id int, cmd string, desc string, outputs []string)
- func (c *Console) Close() error
- func (c *Console) Debugf(format string, a ...any)
- func (c *Console) Errorf(format string, a ...any)
- func (c *Console) Infof(format string, a ...any)
- func (c *Console) PlanHasTotalSteps(total int)
- func (c *Console) Printf(format string, a ...any)
- func (c *Console) Tracef(format string, a ...any)
- func (c *Console) Warnf(format string, a ...any)
- type ContextKey
- type Logger
- type RunParameters
- type Status
- type WarnLevel
Constants ¶
const ( WarnNone = iota WarnWarn WarnError )
WarnLevel values, in increasing order of severity.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CliFlags ¶
type CliFlags struct {
Trace bool
Verbosity int
Quiet bool
ConcurrencyLevel int
DryRun bool
FrontendCmd string
FrontendFile string
FailLimit int
PSICPU float64
PSIMem float64
PSIIO float64
// stats print operation counts/timing info
DebugStats bool
// explain explain what caused a command to execute
DebugExplain bool
// keepdepfile don't delete depfiles after they're read by ninja
DebugKeepDepFile bool
// keeprsp don't delete @response files on success
DebugKeepRSP bool
// nothreads don't use threads to parallelize ninja
DebugNoThreads bool
// dupbuild={err,warn} multiple build lines for one target
WarnDupBuild WarnLevel
// phonycycle={err,warn} phony build statement references itself
WarnPhonyCycle WarnLevel
// depfilemulti={err,warn} depfile has multiple output paths on separate lines
WarnDepFileMulti WarnLevel
// missingdepfile={err,warn} how to treat missing depfiles
WarnMissingDepFile WarnLevel
// requires -o usesphonyoutputs=yes
// outputdir={err,warn} how to treat outputs that are directories
WarnOutputDir WarnLevel
// missingoutfile={err,warn} how to treat missing output files
WarnMissingOutFile WarnLevel
// oldoutput={err,warn} how to treat output files older than their inputs
WarnOldOutput WarnLevel
// requires -o usessymlinkoutputs=yes
// undeclaredsymlinkoutputs={err,warn}
WarnUndeclaredSymlinkOutputs WarnLevel
// usesphonyoutputs={yes,no}: whether the generator uses 'phony_outputs' so
// that these warnings work: outputdir, missingoutfile, oldoutput.
OptUsesPhonyOutputs bool
// usessymlinkoutputs={yes,no}: whether the generator uses 'symlink_outputs'
// so that these warnings work: undeclaredsymlinkoutputs.
OptUsesSymlinkOutputs bool
// preremoveoutputs={yes,no}: whether to remove outputs before running a rule.
OptPreremoveOutputs bool
// usesninjalogasweightlist={yes,no}: whether to use the ninja log as the
// source of the weight list.
OptUsesNinjaLogAsWeightlist bool
// usesweightlist={<file path>,no}: whether to prioritize some rules based
// on a weight list read from the given file.
OptUsesWeightList string
// acceptoutputexists={yes,no}: if true, accept an existing output as valid
// even if it is dirty.
OptAcceptOutputExists bool
// showcachedasdone={yes,no}: if true, show cached steps as done
// (ninjago-specific).
OptShowCachedAsDone bool
// noremote={yes,no}: if true, disable remote execution (ninjago-specific).
OptNoRemote bool
// nolocalfallback={yes,no}: if true, do not fall back to local execution
// when a remote execution fails (ninjago-specific).
OptNoLocalFallback bool
}
CliFlags collects the values of all command-line flags accepted by the ninjago binary.
func (*CliFlags) LoadDebugs ¶
LoadDebugs parses the values supplied via -d and sets the matching debug flags on f.
func (*CliFlags) LoadOptions ¶
LoadOptions parses the values supplied via -o and sets the matching option fields on f.
type CloseFunc ¶
type CloseFunc = func() error
CloseFunc releases resources associated with a mapped or opened file.
type Console ¶
type Console struct {
// contains filtered or unexported fields
}
Console is a Logger implementation that writes status updates and log messages to a terminal.
func NewConsole ¶
func NewConsole(params *RunParameters) *Console
NewConsole constructs a Console using settings from params and the NINJA_STATUS environment variable.
func (*Console) BuildStepCanceled ¶
BuildStepFinished implements Logger.
func (*Console) BuildStepFinished ¶
BuildStepFinished implements Logger.
func (*Console) BuildStepStarted ¶
BuildStepStarted implements Logger.
func (*Console) PlanHasTotalSteps ¶
PlanHasTotalSteps implements Logger.
type ContextKey ¶
type ContextKey string
ContextKey is the type used for keys placed on the context by ninjago.
const ( BackendKey ContextKey = "backend" RunParamsKey ContextKey = "run-params" )
Well-known keys used to attach ninjago values to a context.Context.
type Logger ¶
type Logger interface {
BuildStarted()
BuildFinished()
BuildStepStarted(id int, cmd, desc string, outputs []string)
BuildStepFinished(id int, exitCode int, output string)
BuildStepCanceled(id int)
PlanHasTotalSteps(total int)
Printf(format string, a ...any)
Tracef(format string, a ...any)
Debugf(format string, a ...any)
Infof(format string, a ...any)
Warnf(format string, a ...any)
Errorf(format string, a ...any)
Close() error
}
Logger receives build progress events and log messages.
type RunParameters ¶
type RunParameters struct {
// NinjaFile is the path to the ninja file passed to the CLI (-f flag).
NinjaFile string
// CliFlags holds the flags and options passed to the CLI.
CliFlags *CliFlags
// Prefix is the command prefix used when showing command usage.
Prefix string
// Out is the writer used for command output (distinct from application logs).
Out io.Writer
// Log is the logger used to log messages.
Log Logger
// IsInteractive reports whether the command is being used interactively.
IsInteractive bool
// IsHTTP reports whether the command is being used in HTTP mode.
IsHTTP bool
// CleanInspectorsCount is the number of concurrent clean inspections the build engine runs.
CleanInspectorsCount int
// CacheCheckersCount is the number of concurrent cache checkers the build engine runs.
CacheCheckersCount int
// RemoteExecutorsCount is the maximum number of concurrent remote executions.
RemoteExecutorsCount int
}
RunParameters holds all of the general parameters that are required to run a ninjago command.
func NewRunParams ¶
func NewRunParams() *RunParameters
NewRunParams returns a RunParameters with default values.
func (*RunParameters) Print ¶
func (c *RunParameters) Print(format string, a ...any)
Print writes a formatted message to the configured output, ensuring it ends with a newline.
type Status ¶
type Status struct {
Started int
Total int
Running int
Finished int
Elapsed time.Duration
ETA time.Duration
OverallRate float64
CurrentRate float64
}
Status describes a snapshot of build progress used to render the NINJA_STATUS indicator. See https://ninja-build.org/manual.html#_environment_variables for the format directives accepted by Format.
%s The number of started edges. %t The total number of edges that must be run to complete the build. %p The percentage of finished edges. %r The number of currently running edges. %u The number of remaining edges to start. %f The number of finished edges. %o Overall rate of finished edges per second. %c Current rate of finished edges per second (average over builds specified by -j or its default). %e Elapsed time in seconds. (Available since Ninja 1.2.) %E Remaining time (ETA) in seconds. (Available since Ninja 1.12.) %w Elapsed time in [h:]mm:ss format. (Available since Ninja 1.12.) %W Remaining time (ETA) in [h:]mm:ss format. (Available since Ninja 1.12.) %P The percentage (in ppp%% format) of time elapsed out of predicted total runtime. (Available since Ninja 1.12.) %% A plain %% character.