runtime

package
v0.0.4-d-oss Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 3, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

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

View Source
const (
	WarnNone = iota
	WarnWarn
	WarnError
)

WarnLevel values, in increasing order of severity.

Variables

This section is empty.

Functions

func Get

func Get[T any](ctx context.Context, key ContextKey) T

Get retrieves the value stored under key from ctx and asserts it as T. It panics if the value is missing or has a different type.

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

func (f *CliFlags) LoadDebugs(d []string) error

LoadDebugs parses the values supplied via -d and sets the matching debug flags on f.

func (*CliFlags) LoadOptions

func (f *CliFlags) LoadOptions(o []string) error

LoadOptions parses the values supplied via -o and sets the matching option fields on f.

func (*CliFlags) LoadWarns

func (f *CliFlags) LoadWarns(w []string) error

LoadWarns parses the values supplied via -w and sets the matching warning levels on f.

type CloseFunc

type CloseFunc = func() error

CloseFunc releases resources associated with a mapped or opened file.

func ReadMMapFile

func ReadMMapFile(fileName string) ([]byte, CloseFunc, error)

ReadMMapFile memory-maps the named file for read-only access. The returned CloseFunc unmaps and closes the underlying 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) BuildFinished

func (c *Console) BuildFinished()

BuildFinished implements Logger.

func (*Console) BuildStarted

func (c *Console) BuildStarted()

BuildStarted implements Logger.

func (*Console) BuildStepCanceled

func (c *Console) BuildStepCanceled(id int)

BuildStepFinished implements Logger.

func (*Console) BuildStepFinished

func (c *Console) BuildStepFinished(id int, exitCode int, output string)

BuildStepFinished implements Logger.

func (*Console) BuildStepStarted

func (c *Console) BuildStepStarted(id int, cmd string, desc string, outputs []string)

BuildStepStarted implements Logger.

func (*Console) Close

func (c *Console) Close() error

Close implements Logger.

func (*Console) Debugf

func (c *Console) Debugf(format string, a ...any)

Debugf implements Logger.

func (*Console) Errorf

func (c *Console) Errorf(format string, a ...any)

Errorf implements Logger.

func (*Console) Infof

func (c *Console) Infof(format string, a ...any)

Infof implements Logger.

func (*Console) PlanHasTotalSteps

func (c *Console) PlanHasTotalSteps(total int)

PlanHasTotalSteps implements Logger.

func (*Console) Printf

func (c *Console) Printf(format string, a ...any)

Printf implements Logger.

func (*Console) Tracef

func (c *Console) Tracef(format string, a ...any)

Tracef implements Logger.

func (*Console) Warnf

func (c *Console) Warnf(format string, a ...any)

Warnf 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.

func (*Status) Format

func (s *Status) Format(format string) string

Format expands the NINJA_STATUS-style directives in format using the values from s.

type WarnLevel

type WarnLevel int

WarnLevel describes how a particular warning should be reported.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL