Documentation
¶
Overview ¶
Package config resolves gotools' configuration.
A value can come from three places. In increasing priority:
- the built-in default,
- the manifest file, .gotools.json in the project root,
- the environment, GOTOOLS_*,
- overrides the caller passes, such as command line flags.
Load stacks the three as koanf layers, so a later layer overrides an earlier one key by key, and reads the result into a Config. The manifest is read as JSON by koanf, so Config mirrors its shape: the layout keys at the top level and the settings in a "settings" object. Nothing here reads the process environment; the caller passes it in.
Index ¶
- Constants
- Variables
- func FormatSetting(name string, s Settings) (string, bool)
- func IsKey(name string) bool
- func IsSetting(name string) bool
- func ParseSetting(name, value string, s *Settings) error
- func ValidateDir(dir string) error
- type Config
- type Layout
- type Option
- type Overrides
- type Settings
- type Strategy
- type TraceMode
Constants ¶
const ( EnvVarStrategy = "GOTOOLS_STRATEGY" EnvVarDir = "GOTOOLS_DIR" EnvVarGoVersion = "GOTOOLS_GO_VERSION" EnvVarModulePrefix = "GOTOOLS_MODULE_PREFIX" EnvVarOffline = "GOTOOLS_OFFLINE" EnvVarJobs = "GOTOOLS_JOBS" EnvVarOperationTimeout = "GOTOOLS_OPERATION_TIMEOUT" EnvVarLockTimeout = "GOTOOLS_LOCK_TIMEOUT" EnvVarNoLock = "GOTOOLS_NO_LOCK" EnvVarTrace = "GOTOOLS_TRACE" EnvVarVerbose = "GOTOOLS_VERBOSE" KeyStrategy = "strategy" KeyDir = "dir" KeyGoVersion = "go_version" KeyModulePrefix = "module_prefix" KeyOffline = "settings.offline" KeyJobs = "settings.jobs" KeyOperationTimeout = "settings.operation_timeout" KeyLockTimeout = "settings.lock_timeout" KeyNoLock = "settings.no_lock" KeyTrace = "settings.trace" KeyVerbose = "settings.verbose" DefaultStrategy = StrategySplit DefaultDir = "tools" DefaultGoVersion = "inherit" DefaultModulePrefix = "" DefaultOffline = false DefaultJobs = 1 DefaultOperationTimeout = 120 DefaultLockTimeout = 10 DefaultNoLock = false DefaultTrace = TraceOff DefaultVerbose = false )
The environment variables.
const ( StrategySplit = strategy.Split StrategyModule = strategy.Module StrategyUnified = strategy.Unified )
const DefaultLockStaleTimeout = 300
DefaultLockStaleTimeout is the value reported for EnvVarLockStaleTimeout.
const EnvPrefix = "GOTOOLS_"
EnvPrefix starts the name of every environment variable gotools reads.
const EnvVarLockStaleTimeout = "GOTOOLS_LOCK_STALE_TIMEOUT"
EnvVarLockStaleTimeout is accepted by Keys for compatibility. Nothing reads it, since the lock is released by the kernel when its holder dies.
const ManifestFile = ".gotools.json"
ManifestFile is the manifest's name in the project root.
Variables ¶
var Keys = []string{ EnvVarStrategy, EnvVarDir, EnvVarGoVersion, EnvVarModulePrefix, EnvVarOffline, EnvVarJobs, EnvVarOperationTimeout, EnvVarLockTimeout, EnvVarLockStaleTimeout, EnvVarNoLock, EnvVarTrace, EnvVarVerbose, }
Keys lists the GOTOOLS_* names a user can read and change, in help order. The first four are layout keys; the rest are settings.
Functions ¶
func FormatSetting ¶
FormatSetting returns the settings key name of s in the form it is written and accepted, and false when name is not a settings key.
func IsSetting ¶
IsSetting reports whether name is a key of the settings block, as opposed to a layout key.
func ParseSetting ¶
ParseSetting applies value to the settings key name in s, checking it against the type the setting has: a boolean, a positive number of jobs, a non-negative number of seconds, or a trace mode. Booleans are true, false, 1 or 0; trace also takes stdout. A value that does not fit is a usage error and leaves s unchanged.
func ValidateDir ¶
ValidateDir reports whether dir may serve as the tools directory. It must be a relative path that stays inside the project and is not the project root, since everything in it is created, rewritten and removed.
Types ¶
type Config ¶
Config is the resolved configuration, shaped like the manifest.
func Load ¶
Load resolves the configuration of the project at root. environ lists the environment as NAME=value pairs, like os.Environ; nil means no variables.
A project without a manifest is configured by the defaults and the environment alone. A manifest that is not valid JSON, a value of the wrong type, or a value that fails Validate is an error.
type Layout ¶
type Layout struct {
Strategy Strategy `koanf:"strategy"`
Dir string `koanf:"dir"`
GoVersion string `koanf:"go_version"`
ModulePrefix string `koanf:"module_prefix"`
}
Layout says where the tools live and how they are isolated.
type Option ¶
type Option func(*loadOptions)
Option adjusts how Load resolves the configuration.
func WithOverrides ¶
WithOverrides adds a layer above the environment: default < manifest < environment < overrides.
func WithoutManifest ¶
func WithoutManifest() Option
WithoutManifest leaves the manifest out: the configuration is the defaults, the environment and the overrides. A diagnostic uses it to still resolve a layout when the manifest cannot be read.
type Overrides ¶
Overrides are values that outrank every other layer, such as command line flags. An empty field is not an override.
type Settings ¶
type Settings struct {
Offline bool `koanf:"offline"`
Jobs int `koanf:"jobs"`
OperationTimeout int `koanf:"operation_timeout"`
LockTimeout int `koanf:"lock_timeout"`
NoLock bool `koanf:"no_lock"`
Trace TraceMode `koanf:"trace"`
Verbose bool `koanf:"verbose"`
}
Settings are the runtime knobs. Durations are in seconds.
Source Files