build

func OptLogsink ¶

func OptLogsink(c *streamclient.Client) StartOption

OptLogsink allows you to associate a streamclient with the started build.

See `streamclient.New` and `streamclient.NewFake` for how to create a client suitable to your needs (note that this includes a local filesystem option).

If a logsink is configured, it will be used as the output destination for the go.chromium.org/luci/common/logging library, and will recieve all data written via the Loggable interface.

If no logsink is configured, the go.chromium.org/luci/common/logging library will be unaffected, and data written to the Loggable interface will go to an ioutil.NopWriteCloser.

func OptOutputProperties ¶

func OptOutputProperties(writeFnptr, mergeFnptr any) StartOption

OptOutputProperties allows you to register a property writer for the top-level output properties of the build.

The registered message must not have any fields which conflict with a namespace reserved with MakePropertyModifier, or this panics.

This works like MakePropertyModifier, except that it works at the top level (i.e. no namespace) and the functions operate directly on the State (i.e. they do not take a context).

Usage

var writer func(*MyMessage)
var merger func(*MyMessage)

// one function may be nil and will be skipped
... = Start(, ..., OptOutputProperties(&writer, &merger))

in go2 this can be improved (possibly by making State a generic type):

func OptParseProperties ¶

func OptParseProperties(msg proto.Message) StartOption

OptParseProperties allows you to parse the build's Input.Properties field as JSONPB into the given protobuf message.

Message fields which overlap with property namespaces reserved by MakePropertyReader will not be populated (i.e. all property namespaces reserved with MakePropertyReader will be removed before parsing into this message).

Type mismatches (i.e. parsing a non-numeric string into an int field) will report an error and quit the build.

Example:

msg := &MyOutputMessage{}
state, ctx := Start(ctx, inputBuild, OptParseProperties(msg))
# `msg` has been populated from inputBuild.InputProperties

func OptSend ¶

func OptSend(lim rate.Limit, callback func(int64, *bbpb.Build)) StartOption

OptSend allows you to get a callback when the state of the underlying Build changes.

This callback will be called at most as frequently as `rate` allows, up to once per Build change, and is called with the version number and a copy of Build. Only one outstanding invocation of this callback can occur at once.

If new updates come in while this callback is blocking, they will apply silently in the background, and as soon as the callback returns (and rate allows), it will be invoked again with the current Build state.

Every modification of the Build state increments the version number by one, even if it doesn't result in an invocation of the callback. If your program modifies the build state from multiple threads, then the version assignment is arbitrary, but if you make 10 parallel changes, you'll see the version number jump by 10 (and you may, or may not, observe versions in between).

func OptStrictInputProperties ¶

func OptStrictInputProperties() StartOption

OptStrictInputProperties will cause the build to report an error if data is passed via Input.Properties which wasn't parsed into OptParseProperties or MakePropertyReader.

func Start ¶

func Start(ctx context.Context, initial *bbpb.Build, opts ...StartOption) (*State, context.Context, error)

Start is the 'inner' entrypoint to this library.

If you're writing a standalone luciexe binary, see `Main` and `MainWithOutput`.

This function clones `initial` as the basis of all state updates (see OptSend) and MakePropertyReader declarations. This also initializes the build State in `ctx` and returns the manipulable State object.

You must End the returned State. To automatically map errors and panics to their correct visual representation, End the State like:

var err error
state, ctx := build.Start(ctx, initialBuild, ...)
defer func() { state.End(err) }()

err = opThatErrsOrPanics(ctx)

NOTE: A panic will still crash the program as usual. This does NOT `recover()` the panic. Please use conventional Go error handling and control flow mechanisms.

func ScheduleStep ¶

func ScheduleStep(ctx context.Context, name string) (*Step, context.Context)

ScheduleStep is like StartStep, except that it leaves the new step in the SCHEDULED status, and does not set a StartTime.

The step will move to STARTED when calling any other methods on the Step, when creating a sub-Step, or if you explicitly call Step.Start().

func StartStep ¶

func StartStep(ctx context.Context, name string) (*Step, context.Context)

StartStep adds a new step to the build.

The step will have a "STARTED" status with a StartTime.

If `name` contains `|` this function will panic, since this is a reserved character for delimiting hierarchy in steps.

Duplicate step names will be disambiguated by appending " (N)" for the 2nd, 3rd, etc. duplicate.

The returned context has the following changes:

1. It contains the returned *Step as the current step, which means that calling the package-level StartStep/ScheduleStep on it will create sub-steps of this one.
2. The returned context also has an updated `environ.FromCtx` containing a unique $LOGDOG_NAMESPACE value. If you launch a subprocess, you should use this environment to correctly namespace any logdog log streams your subprocess attempts to open. Using `go.chromium.org/luci/luciexe/build/exec` does this automatically.
3. `go.chromium.org/luci/common/logging` is wired up to a new step log stream called "log".

You MUST call Step.End. To automatically map errors and panics to their correct visual representation, End the Step like:

var err error
step, ctx := build.StartStep(ctx, "Step name")
defer func() { step.End(err) }()

err = opThatErrsOrPanics(ctx)

NOTE: A panic will still crash the program as usual. This does NOT `recover()` the panic. Please use conventional Go error handling and control flow mechanisms.