blob: 00bade9f60a65d1ee8f61ef125de891d7931cd49 [file] [log] [blame]
// Copyright 2020 The LUCI Authors.
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
// Package build implements a minimal, safe, easy-to-use, hard-to-use-wrong,
// 'luciexe binary' implementation in Go.
// See `Start` for the entrypoint to this API.
// Features:
// * Can be used in library code which is used in both luciexe and non-luciexe
// contexts. You won't need "two versions" of your library just to give it
// the appearance of steps in a LUCI build context, or to have it read or
// write build properties.
// * Goroutine-safe API.
// * Handles all interactions with the log sink (e.g. LogDog), and
// automatically reroutes the logging library if a log sink is configured
// (so all log messages will be preserved in a build context).
// * Handles coalescing all build mutations from multiple goroutines.
// Efficient throttling for outgoing updates.
// * Automatically upholds all luciexe protocol invariants; Avoids invalid
// Build states by construction.
// * Automatically maps errors and panics to their obvious visual
// representation in the build (and allows manual control in case you want
// something else).
// * Fully decoupled from LUCI service implementation; You can use this API
// with no external services (e.g. for a CLI application), backed with the
// real LUCI implementation (e.g. when running under BuildBucket), and in
// tests (you can observe all outputs from this API without any live
// services or heavy mocks).
// No-Op Mode
// When no Build is in use in the context, the library behaves in 'no-op' mode.
// This should enable libraries to add `build` features which gracefully degrade
// into pure terminal output via logging.
// * MakePropertyReader functions will return empty messages. Well-behaved
// libraries should handle having no configuration in the context if this is
// possible.
// * There will be no *State object, because there is no Start call.
// * StartStep/ScheduleStep will return a *Step which is detached. Step
// namespacing will still work in context (but name deduplication will not).
// * The result of State.Modify/Step.Modify (and Set) calls will be
// logged at DEBUG.
// * Step scheduled/started/ended messages will be logged at INFO.
// Ended log messages will include the final summary markdown as well.
// * Text logs will be logged line-by-line at INFO with fields set indicating
// which step and log they were emitted from. Debug text logs (those whose
// log names start with "$") will be logged at DEBUG level.
// * Non-text logs will be dropped with a WARNING indicating that they're
// being dropped.
// * MakePropertyReader property readers will return empty message objects.
// * MakePropertyModifier property manipulators will log their emitted
// properties at INFO.
package build
// BUG(iannucci): When OptLogsink is used and `logging` output is redirected to
// a Step log entitled "log", the current log format is reset to
// `gologger.StdFormat` instead of preserving the current log format from the
// context.