gomkore

package
v0.11.15 Latest Latest
Warning

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

 Go to latest Published: Apr 16, 2024 License: AGPL-3.0 Imports: 17 Imported by: 1

Documentation

Overview

Package gomkore implements the core model of gomk for the representation of buildable projects. It uses idiomatic Go error handling, which can make writing gomk build scripts a bit cumbersome. However, this package serves as a solid foundation for implementing build strategies, such as updating artifacts depending on their prerequisites or propagating artifact changes to dependent artifacts. The core concepts are Project, Goal and Action. An easy-to-use wrapper for everyday use in build scripts is provided by the gomk package.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Clean added in v0.11.13 

func Clean(prj *Project, dryrun bool, tr *Trace) error

Types

type Abstract 

type Abstract string

func (Abstract) Key added in v0.11.14 

func (a Abstract) Key() any

func (Abstract) Name 

func (a Abstract) Name(*Project) string

func (Abstract) StateAt 

func (a Abstract) StateAt(prj *Project) (t time.Time, err error)

type Action 

type Action struct {
	Op          Operation
	IgnoreError bool
	// contains filtered or unexported fields
}

An Action is something you can do in your Project to achieve at least one Goal. The actual implementation of the action is an Operation. An action without an operation is an "implicit" action, i.e. if all its premises are true, all results of the action are implicitly given.

func (*Action) LastBuild 

func (a *Action) LastBuild() BuildID

func (*Action) Premise 

func (a *Action) Premise(i int) *Goal

func (*Action) Premises 

func (a *Action) Premises() []*Goal

func (*Action) Project 

func (a *Action) Project() *Project

func (*Action) Result 

func (a *Action) Result(i int) *Goal

func (*Action) Results 

func (a *Action) Results() []*Goal

func (*Action) Run 

func (a *Action) Run(tr *Trace, env *Env) (BuildID, error)

Must not run concurrently, see Goal.LockPreActions and [tryLock]

func (*Action) String 

func (a *Action) String() string

func (*Action) WriteHash 

func (a *Action) WriteHash(h hash.Hash, env *Env) (bool, error)

type Artefact 

type Artefact interface {
	Key() any

	// Name returns the name of the artefact that must be unique in the Project.
	Name(in *Project) string

	// StateAs returns the time at which the artefact reached its current state.
	// If this cannot be provided, the zero Time is returned.
	StateAt(in *Project) (time.Time, error)
}

Artefact represents the tangible outcome of a Goal being reached. A special case is the Abstract artefact.

type BuildID 

type BuildID = uint64

type BuildTracer added in v0.11.13 

type BuildTracer interface {
	TracerCommon

	RunAction(*Trace, *Action)
	RunImplicitAction(*Trace, *Action)

	ScheduleResTimeZero(t *Trace, a *Action, res *Goal)
	ScheduleNotPremises(t *Trace, a *Action, res *Goal)
	SchedulePreTimeZero(t *Trace, a *Action, res, pre *Goal)
	ScheduleOutdated(t *Trace, a *Action, res, pre *Goal)

	CheckGoal(t *Trace, g *Goal)
	GoalUpToDate(t *Trace, g *Goal)
	GoalNeedsActions(t *Trace, g *Goal, n int)
}

type Builder added in v0.11.13 

type Builder struct {
	// contains filtered or unexported fields
}

TODO Add a "dry-run" option

func NewBuilder added in v0.11.14 

func NewBuilder(tr *Trace, env *Env) (*Builder, error)

func (*Builder) Describe added in v0.11.13 

func (bd *Builder) Describe(*Action, *Env) string

func (*Builder) Do added in v0.11.13 

func (bd *Builder) Do(tr *Trace, a *Action, env *Env) error

func (*Builder) Goals added in v0.11.13 

func (bd *Builder) Goals(gs ...*Goal) error

func (*Builder) NamedGoals added in v0.11.13 

func (bd *Builder) NamedGoals(prj *Project, names ...string) error

func (*Builder) Project added in v0.11.13 

func (bd *Builder) Project(prj *Project) error

Project builds all leafs in prj.

func (*Builder) Trace added in v0.11.14 

func (up *Builder) Trace() *Trace

func (*Builder) WriteHash added in v0.11.13 

func (bd *Builder) WriteHash(h hash.Hash, a *Action, env *Env) (bool, error)

type Changer added in v0.11.13 

type Changer struct {
	// contains filtered or unexported fields
}

func NewChanger added in v0.11.14 

func NewChanger(tr *Trace, env *Env) (*Changer, error)

func (*Changer) Goals added in v0.11.14 

func (chg *Changer) Goals(gs ...*Goal) error

func (*Changer) Trace added in v0.11.14 

func (up *Changer) Trace() *Trace

type CleanTracer added in v0.11.13 

type CleanTracer interface {
	TracerCommon

	RemoveArtefact(*Trace, *Goal)
}

type Env 

type Env struct {
	In       io.Reader
	Out, Err io.Writer
	// contains filtered or unexported fields
}

func DefaultEnv 

func DefaultEnv(tr *Trace) *Env

func (*Env) Clone 

func (e *Env) Clone() *Env

func (*Env) DelTag 

func (e *Env) DelTag(key string)

func (*Env) ExecEnv 

func (e *Env) ExecEnv() ([]string, error)

func (*Env) SetTag 

func (e *Env) SetTag(key, val string)

func (*Env) SetTags 

func (e *Env) SetTags(env ...string)

func (*Env) SetTagsMap 

func (e *Env) SetTagsMap(tags map[string]string)

func (*Env) Sub 

func (e *Env) Sub() *Env

func (*Env) Tag 

func (e *Env) Tag(key string) (string, bool)

type Goal 

type Goal struct {
	UpdateMode UpdateMode
	Artefact   Artefact
	Removable  bool

	sync.Mutex
	// contains filtered or unexported fields
}

A Goal is something you want to achieve in your Project. Each goal is associated with an Artefact – generally something tangible that is considered available and up-to-date when the goal is achieved. A special case is the Abstract artefact that simply provides a name for abstract goals. Abstract goals do not deliver tangible results.

Goals can be achieved through actions (Action). A goal can be the result of several actions at the same time. It then depends on the target's UpdateMode whether and how the actions contribute to the target. On the other hand, a goal can also be the premise for one or more actions. Such dependent actions should not be carried out before the goal is reached.

func (*Goal) CheckPreTimes added in v0.11.12 

func (g *Goal) CheckPreTimes(tr *Trace) (chgs []int, err error)

CheckPreTimes check if g needs to be updated according to the timestamps of all of its premises.

func (*Goal) IsAbstract 

func (g *Goal) IsAbstract() bool

func (*Goal) LockBuild 

func (g *Goal) LockBuild() BuildID

LockBuild locks g once for the current build of g's project. If g was already locked for the build 0 is returned.

func (*Goal) LockPreActions 

func (g *Goal) LockPreActions(gid uintptr)

func (*Goal) Name 

func (g *Goal) Name() string

func (*Goal) PostAction added in v0.11.12 

func (g *Goal) PostAction(i int) *Action

PostAction returns Goal.PremiseOf()[i]

func (*Goal) PreAction added in v0.11.12 

func (g *Goal) PreAction(i int) *Action

PreAction returns Goal.ResultOf()[i]

func (*Goal) PremiseOf 

func (g *Goal) PremiseOf() []*Action

PremiseOf returns the actions on which g depends.

func (*Goal) Project 

func (g *Goal) Project() *Project

func (*Goal) ResultOf 

func (g *Goal) ResultOf() []*Action

ResultOf returns the actions that result in this goal.

func (*Goal) String 

func (g *Goal) String() string

func (*Goal) UnlockPreActions 

func (g *Goal) UnlockPreActions()

func (*Goal) UpdateConsistency 

func (g *Goal) UpdateConsistency(involved *Goal) error

Requires 'involved' to really be involved

type GoalFactory added in v0.11.14 

type GoalFactory interface {
	Goals(in *Project) ([]*Goal, error)
}

type NonXEnvKeys 

type NonXEnvKeys []string

func (NonXEnvKeys) Error 

func (e NonXEnvKeys) Error() string

func (NonXEnvKeys) Is 

func (NonXEnvKeys) Is(target error) bool

type Operation 

type Operation interface {
	// The hints are optional
	Describe(actionHint *Action, envHint *Env) string
	Do(tr *Trace, a *Action, env *Env) error
	WriteHash(h hash.Hash, a *Action, env *Env) (bool, error)
}

type Project 

type Project struct {
	Dir string

	sync.Mutex
	// contains filtered or unexported fields
}

func NewProject 

func NewProject(dir string) *Project

func (*Project) AbsPath added in v0.11.12 

func (prj *Project) AbsPath(rel string) (string, error)

func (*Project) Actions added in v0.11.12 

func (prj *Project) Actions() []*Action

func (*Project) Build added in v0.11.13 

func (prj *Project) Build() BuildID

func (*Project) FindGoal 

func (prj *Project) FindGoal(name string) *Goal

func (*Project) Goal 

func (prj *Project) Goal(atf Artefact) (*Goal, error)

func (*Project) Goals 

func (prj *Project) Goals(addTo []*Goal) []*Goal

TODO interator as soon as it is available

func (*Project) Key added in v0.11.14 

func (prj *Project) Key() any

func (*Project) Leafs 

func (prj *Project) Leafs() (ls []*Goal)

func (*Project) LockBuild 

func (prj *Project) LockBuild() BuildID

func (*Project) Name 

func (prj *Project) Name(in *Project) string

func (*Project) NewAction 

func (prj *Project) NewAction(premises, results []*Goal, op Operation) (*Action, error)

NewAction creates a new Action in project prj. There must be at least one result. All premises and results must belong to the same project prj.

func (*Project) RelPath 

func (prj *Project) RelPath(p string) (dir string, err error)

func (*Project) RelPathTo added in v0.11.13 

func (prj *Project) RelPathTo(base, relTarget string) (string, error)

func (*Project) Roots 

func (prj *Project) Roots() (rs []*Goal)

func (*Project) StateAt 

func (prj *Project) StateAt(in *Project) (time.Time, error)

func (*Project) String 

func (prj *Project) String() string

type RemovableArtefact added in v0.11.13 

type RemovableArtefact interface {
	Artefact
	Exists(in *Project) (bool, error)
	Remove(in *Project) error
}

type Trace added in v0.11.13 

type Trace struct {
	// contains filtered or unexported fields
}

func NewTrace added in v0.11.13 

func NewTrace(ctx context.Context, t Tracer) *Trace

func (*Trace) Build added in v0.11.13 

func (t *Trace) Build() BuildID

func (*Trace) Ctx added in v0.11.13 

func (t *Trace) Ctx() context.Context

func (*Trace) Debug added in v0.11.13 

func (t *Trace) Debug(msg string, args ...any)

func (*Trace) Info added in v0.11.13 

func (t *Trace) Info(msg string, args ...any)

func (*Trace) Path added in v0.11.13 

func (t *Trace) Path() string

func (*Trace) String added in v0.11.13 

func (t *Trace) String() string

func (*Trace) TopID added in v0.11.13 

func (t *Trace) TopID() uint64

func (*Trace) TopTag added in v0.11.13 

func (t *Trace) TopTag() string

func (*Trace) Warn added in v0.11.13 

func (t *Trace) Warn(msg string, args ...any)

type Tracer added in v0.11.13 

type Tracer interface {
	BuildTracer
	CleanTracer
}

type TracerCommon added in v0.11.13 

type TracerCommon interface {
	Debug(t *Trace, msg string, args ...any)
	Info(t *Trace, msg string, args ...any)
	Warn(t *Trace, msg string, args ...any)

	StartProject(t *Trace, p *Project, activity string)
	DoneProject(t *Trace, p *Project, activity string, dt time.Duration)

	SetupActionEnv(t *Trace, env *Env) (*Env, error)
	CloseActionEnv(t *Trace, env *Env) error
}

type UpdateMode 

type UpdateMode uint
const (
	// All actions must be run to reach the goal.
	UpdAllActions UpdateMode = 0

	// All actions with changed state must be run to reach the goal.
	UpdSomeActions UpdateMode = 1

	// Only one of the actions with changed state has to be run to reach the
	// goal.
	UpdAnyAction UpdateMode = 2

	// Only one action must have changed state. Then the goal is reached by
	// running that action.
	UpdOneAction UpdateMode = 3

	// An unordered update mode allows actions of the current goal to be run in
	// any order or even concurrently. Otherwise, the actions must be run one
	// after the other in the specified order.
	UpdUnordered UpdateMode = 4
)

func (UpdateMode) Actions 

func (m UpdateMode) Actions() UpdateMode

func (UpdateMode) Ordered 

func (m UpdateMode) Ordered() bool

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.