gomk

package module
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: 20 Imported by: 5

README

gomk - Make things Go

Go Reference

Note: The v0.11 series is for experiments and rewriting

  • Just a Go library module, no extra DSL to learn, and your Go IDE will help you right away.

  • As portable as Go is – as long as you don't add any platform specifics.

  • No extra tools implied. Having Go SDK installed, run a build script with go run.

You will find the details in the Go docs. For a more pragmatic approach, you should take a look at the example project.

Documentation

Overview

Package gomk helps to write build scripts in Go for projects where just running 'go build' is not enough. Instead of using platform-specific tools, a build script written in Go can better ensure platform independence. gomk is built around the core concepts of [Project], [Goal] and [Action]. The details are described in sub package gomkore. This packge wraps the code model from gomkore with a user-friendly API for building projects (see Edit).

gomk is just a Go library. Is can be used in any context of reasonable programming with Go. But gomk is not a comprehensive library for all types of project builds. It is focussed on the fundamentals of a build system. Specific applications shall be implemented in separate libraries, such as gomk-lib.

Nevertheless, a few conventions can be helpful. A build script is a Go executable. As such it cannot be used by other packages (using plugins is not considered, primarily for not generally being portable). 

"mk.go" is the recommended file name for a build script

The build scripts of a project must not collide with the rest of the code. Here are a few ideas for structuring the build scripts:

Simple Go project with source in the root directory 

module/
├── bar.go
├── foo.go
├── go.mod
├── go.sum
└── mk
    └── mk.go

Build with 

module$ go run mk/mk.go

Go project without code in the root directory 

module/
├── cmd
│   ├── bar
│   │   └── main.go
│   └── foo
│       └── main.go
├── explib
│   └── stuff.go
├── go.mod
├── go.sum
├── internal
│   └── lib.go
└── mk.go

Build with 

module$ go run mk.go

Editing Projects 

TODO: gomkore vs. simple API through [gomk.Edit]
Example (PrefixWriter) 
pw := newPrefixWriterString(os.Stdout, "PRE:")
io.WriteString(pw, "foo")
io.WriteString(pw, "bar\n")
io.WriteString(pw, "baz\nquux")

Output:

PRE:foobar
PRE:baz
PRE:quux

Index

Examples

Constants

View Source 
const (
	UpdAllActions  gomkore.UpdateMode = 0
	UpdSomeActions gomkore.UpdateMode = 1
	UpdAnyAction   gomkore.UpdateMode = 2
	UpdOneAction   gomkore.UpdateMode = 3

	UpdUnordered gomkore.UpdateMode = 4
)
View Source 
const (
	TraceImportant TraceLevel = (1 << iota)
	TraceNormal
	TraceDetails

	TraceNothing = 0
	TraceLeast   = TraceImportant
	TraceMedium  = TraceLeast | TraceNormal
	TraceMost    = TraceMedium | TraceDetails
)
View Source 
const WriteTraceLevelFlagDoc = `Set trace level: l/least; m/medium; M/most`

Variables

This section is empty.

Functions

func AType added in v0.11.12 

func AType[A gomkore.Artefact](g *gomkore.Goal) bool

func Clean added in v0.11.6 

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

func Edit added in v0.11.9 

func Edit(prj *gomkore.Project, do func(prj ProjectEd)) (err error)

Edit calls do with wrappers of gomkore types that allow easy editing of project definitions. Edit recovers from any panic and returns it as an error, so the idiomatic error handling within do can be skipped.

func Goals added in v0.11.12 

func Goals(gs []*gomkore.Goal, exclusive bool, matchAll ...func(*gomkore.Goal) bool) ([]*gomkore.Goal, error)

Goals is meant to be used when implementing [Operation] to select and check linked goals gs.

See also Tangible, AType

func NewBuilder added in v0.11.14 

func NewBuilder(tr *gomkore.Trace, env *gomkore.Env) *gomkore.Builder

func NewChanger added in v0.11.14 

func NewChanger(tr *gomkore.Trace, env *gomkore.Env) *gomkore.Changer

func OpFunc added in v0.11.11 

func OpFunc(desc string, f func(*gomkore.Trace, *gomkore.Action, *gomkore.Env) error) gomkore.Operation

func Tangible added in v0.11.11 

func Tangible(g *gomkore.Goal) bool

Types

type ActionEd added in v0.11.9 

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

ActionEd is used with Edit.

func (ActionEd) Action added in v0.11.12 

func (ed ActionEd) Action() *gomkore.Action

func (ActionEd) Project added in v0.11.9 

func (ed ActionEd) Project() ProjectEd

func (ActionEd) SetIgnoreError added in v0.11.9 

func (ed ActionEd) SetIgnoreError(ignore bool)

type CmdOp added in v0.11.0 

type CmdOp struct {
	CWD             string
	Exe             string
	Args            []string
	InFile, OutFile string
	Desc            string
	UsesEnv         []string
}

func (*CmdOp) Describe added in v0.11.0 

func (op *CmdOp) Describe(a *gomkore.Action, _ *gomkore.Env) string

func (*CmdOp) Do added in v0.11.0 

func (op *CmdOp) Do(tr *gomkore.Trace, a *gomkore.Action, env *gomkore.Env) error

func (*CmdOp) WriteHash added in v0.11.6 

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

WriteHash considers env only if op.UsesEnv is set correctly.

type ConvertCmd added in v0.11.6 

type ConvertCmd struct {
	Exe  string
	Args []string

	// PassOut controls how the output of the convert command is to be passed to
	// the command:
	// "1"     : The output file name is put after .Args before the input file name.
	// "2"     : The output file name is put after input file name, i.e. as the last argument.
	// "stdout": Stdout is redirected to the output file.
	// "-"<opt>: Flags to set output file name, e.g. "-o".
	PassOut string

	// If the convert command interprets the output relative to the input
	// instead of the current working directory.
	OutRelToIn bool

	// If the convert command wants the output directiory instead of the output
	// file name.
	OutDir bool

	mkfs.MkDirs
}

func (*ConvertCmd) Describe added in v0.11.9 

func (cc *ConvertCmd) Describe(*gomkore.Action, *gomkore.Env) string

func (*ConvertCmd) Do added in v0.11.9 

func (cc *ConvertCmd) Do(tr *gomkore.Trace, a *gomkore.Action, env *gomkore.Env) error

func (*ConvertCmd) WriteHash added in v0.11.9 

func (cc *ConvertCmd) WriteHash(hash.Hash, *gomkore.Action, *gomkore.Env) (bool, error)

type Diagrammer added in v0.11.12 

type Diagrammer struct {
	RankDir string
}

func (*Diagrammer) WriteDot added in v0.11.12 

func (dia *Diagrammer) WriteDot(w io.Writer, prj *gomkore.Project) (err error)

type ExtMap added in v0.11.12 

type ExtMap = map[string]string

type GoBuild added in v0.11.0 

type GoBuild struct {
	GoTool
	Install  bool
	TrimPath bool
	LDFlags  []string // See https://pkg.go.dev/cmd/link
	SetVars  []string // See https://pkg.go.dev/cmd/link Flag: -X
}

GoBuild is an [ActionBuilder] that expects exactly one result [Goal] with either a [File] or [Directory] artefact. The created action will run 'go build' with -C to change into the result's deirectory.

func (*GoBuild) Describe added in v0.11.9 

func (gb *GoBuild) Describe(a *gomkore.Action, _ *gomkore.Env) string

func (*GoBuild) Do added in v0.11.9 

func (gb *GoBuild) Do(tr *gomkore.Trace, a *gomkore.Action, env *gomkore.Env) error

func (*GoBuild) WriteHash added in v0.11.9 

func (*GoBuild) WriteHash(hash.Hash, *gomkore.Action, *gomkore.Env) (bool, error)

type GoGenerate added in v0.11.0 

type GoGenerate struct {
	GoTool
	CWD       string
	FilesPkgs []string // TODO use action prems instead
	Run       string
	Skip      string
}

func (*GoGenerate) Describe added in v0.11.9 

func (gg *GoGenerate) Describe(a *gomkore.Action, _ *gomkore.Env) string

func (*GoGenerate) Do added in v0.11.9 

func (gg *GoGenerate) Do(tr *gomkore.Trace, a *gomkore.Action, env *gomkore.Env) error

func (*GoGenerate) WriteHash added in v0.11.9 

func (*GoGenerate) WriteHash(hash.Hash, *gomkore.Action, *gomkore.Env) (bool, error)

type GoRun added in v0.11.6 

type GoRun struct {
	GoTool
	CWD  string
	Exec string
	Pkg  string // TODO use action prems instead (>1)
	Args []string
}

func (*GoRun) Describe added in v0.11.9 

func (gr *GoRun) Describe(a *gomkore.Action, _ *gomkore.Env) string

func (*GoRun) Do added in v0.11.9 

func (gr *GoRun) Do(tr *gomkore.Trace, a *gomkore.Action, env *gomkore.Env) error

func (*GoRun) WriteHash added in v0.11.9 

func (*GoRun) WriteHash(hash.Hash, *gomkore.Action, *gomkore.Env) (bool, error)

type GoTest added in v0.11.0 

type GoTest struct {
	GoTool
	CWD  string
	Pkgs []string // TODO use action prems instead
}

func (*GoTest) Describe added in v0.11.9 

func (gt *GoTest) Describe(a *gomkore.Action, _ *gomkore.Env) string

func (*GoTest) Do added in v0.11.9 

func (gt *GoTest) Do(tr *gomkore.Trace, a *gomkore.Action, env *gomkore.Env) error

func (*GoTest) WriteHash added in v0.11.9 

func (*GoTest) WriteHash(hash.Hash, *gomkore.Action, *gomkore.Env) (bool, error)

type GoTool added in v0.11.0 

type GoTool struct {
	GoExe string
}

type GoalEd added in v0.11.9 

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

GoalEd is used with Edit.

func Convert added in v0.11.9 

func Convert(
	prems []GoalEd,
	result func(GoalEd) gomkore.Artefact,
	goalCfg func(GoalEd),
	op gomkore.Operation,
	actionCfg func(ActionEd),
) (gls []GoalEd)

func GoalEds added in v0.11.14 

func GoalEds(prj ProjectEd, f gomkore.GoalFactory) (geds []GoalEd)

func (GoalEd) Artefact added in v0.11.9 

func (ed GoalEd) Artefact() gomkore.Artefact

func (GoalEd) By added in v0.11.9 

func (result GoalEd) By(op gomkore.Operation, premises ...GoalEd) (GoalEd, ActionEd)

func (GoalEd) Goal added in v0.11.12 

func (ed GoalEd) Goal() *gomkore.Goal

func (GoalEd) ImpliedBy added in v0.11.9 

func (ed GoalEd) ImpliedBy(premises ...GoalEd) GoalEd

func (GoalEd) IsAbstract added in v0.11.9 

func (ed GoalEd) IsAbstract() bool

func (GoalEd) Project added in v0.11.9 

func (ed GoalEd) Project() ProjectEd

func (GoalEd) Removable added in v0.11.13 

func (ed GoalEd) Removable() bool

func (GoalEd) SetRemovable added in v0.11.13 

func (ed GoalEd) SetRemovable(flag bool)

func (GoalEd) SetUpdateMode added in v0.11.9 

func (ed GoalEd) SetUpdateMode(m gomkore.UpdateMode)

func (GoalEd) UpdateMode added in v0.11.9 

func (ed GoalEd) UpdateMode() gomkore.UpdateMode

type OutFile added in v0.11.12 

type OutFile struct {
	Strip, Dest mkfs.Directory
	Ext         ExtMap
}

func (OutFile) Artefact added in v0.11.12 

func (x OutFile) Artefact(g GoalEd) gomkore.Artefact

type PipeOp added in v0.11.0 

type PipeOp []CmdOp

func (PipeOp) Describe added in v0.11.6 

func (po PipeOp) Describe(a *gomkore.Action, env *gomkore.Env) string

func (PipeOp) Do added in v0.11.0 

func (po PipeOp) Do(tr *gomkore.Trace, a *gomkore.Action, env *gomkore.Env) error

func (PipeOp) WriteHash added in v0.11.6 

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

type ProjectEd added in v0.11.9 

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

ProjectEd is used with Edit.

func (ProjectEd) AbstractGoal added in v0.11.14 

func (ed ProjectEd) AbstractGoal(name string) GoalEd

func (ProjectEd) Dir added in v0.11.9 

func (ed ProjectEd) Dir() string

func (ProjectEd) FsExists added in v0.11.12 

func (ed ProjectEd) FsExists(a mkfs.Artefact) bool

func (ProjectEd) FsStat added in v0.11.12 

func (ed ProjectEd) FsStat(a mkfs.Artefact) fs.FileInfo

func (ProjectEd) Goal added in v0.11.9 

func (ed ProjectEd) Goal(atf gomkore.Artefact) GoalEd

func (ProjectEd) NewAction added in v0.11.9 

func (ed ProjectEd) NewAction(premises, results []GoalEd, op gomkore.Operation) ActionEd

func (ProjectEd) Project added in v0.11.12 

func (ed ProjectEd) Project() *gomkore.Project

func (ProjectEd) RelPath added in v0.11.9 

func (ed ProjectEd) RelPath(p string) string

type TestTracer added in v0.11.13 

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

func (TestTracer) CheckGoal added in v0.11.13 

func (tr TestTracer) CheckGoal(t *gomkore.Trace, g *gomkore.Goal)

func (TestTracer) CloseActionEnv added in v0.11.14 

func (tr TestTracer) CloseActionEnv(t *gomkore.Trace, env *gomkore.Env) error

func (TestTracer) Debug added in v0.11.13 

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

func (TestTracer) DoneProject added in v0.11.13 

func (tr TestTracer) DoneProject(t *gomkore.Trace, p *gomkore.Project, activity string, dt time.Duration)

func (TestTracer) GoalNeedsActions added in v0.11.13 

func (tr TestTracer) GoalNeedsActions(t *gomkore.Trace, g *gomkore.Goal, n int)

func (TestTracer) GoalUpToDate added in v0.11.13 

func (tr TestTracer) GoalUpToDate(t *gomkore.Trace, g *gomkore.Goal)

func (TestTracer) Info added in v0.11.13 

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

func (TestTracer) RemoveArtefact added in v0.11.13 

func (tr TestTracer) RemoveArtefact(t *gomkore.Trace, g *gomkore.Goal)

func (TestTracer) RunAction added in v0.11.13 

func (tr TestTracer) RunAction(_ *gomkore.Trace, a *gomkore.Action)

func (TestTracer) RunImplicitAction added in v0.11.13 

func (tr TestTracer) RunImplicitAction(_ *gomkore.Trace, a *gomkore.Action)

func (TestTracer) ScheduleNotPremises added in v0.11.13 

func (tr TestTracer) ScheduleNotPremises(t *gomkore.Trace, a *gomkore.Action, res *gomkore.Goal)

func (TestTracer) ScheduleOutdated added in v0.11.13 

func (tr TestTracer) ScheduleOutdated(t *gomkore.Trace, a *gomkore.Action, res, pre *gomkore.Goal)

func (TestTracer) SchedulePreTimeZero added in v0.11.13 

func (tr TestTracer) SchedulePreTimeZero(t *gomkore.Trace, a *gomkore.Action, res, pre *gomkore.Goal)

func (TestTracer) ScheduleResTimeZero added in v0.11.13 

func (tr TestTracer) ScheduleResTimeZero(t *gomkore.Trace, a *gomkore.Action, res *gomkore.Goal)

func (TestTracer) SetupActionEnv added in v0.11.14 

func (tr TestTracer) SetupActionEnv(t *gomkore.Trace, env *gomkore.Env) (*gomkore.Env, error)

func (TestTracer) StartProject added in v0.11.13 

func (tr TestTracer) StartProject(t *gomkore.Trace, p *gomkore.Project, activity string)

func (TestTracer) Warn added in v0.11.13 

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

type TraceLevel added in v0.11.14 

type TraceLevel int
var DefaultTraceLevel TraceLevel = TraceLeast

func (TraceLevel) Traces added in v0.11.14 

func (cfg TraceLevel) Traces(l TraceLevel) bool

type WriteTracer added in v0.11.13 

type WriteTracer struct {
	W   io.Writer
	Log TraceLevel
}

func NewDefaultTracer added in v0.11.14 

func NewDefaultTracer() *WriteTracer

func (WriteTracer) CheckGoal added in v0.11.13 

func (tr WriteTracer) CheckGoal(t *gomkore.Trace, g *gomkore.Goal)

func (WriteTracer) CloseActionEnv added in v0.11.14 

func (tr WriteTracer) CloseActionEnv(t *gomkore.Trace, env *gomkore.Env) error

func (WriteTracer) Debug added in v0.11.13 

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

func (WriteTracer) DoneProject added in v0.11.13 

func (tr WriteTracer) DoneProject(t *gomkore.Trace, p *gomkore.Project, activity string, dt time.Duration)

func (WriteTracer) GoalNeedsActions added in v0.11.13 

func (tr WriteTracer) GoalNeedsActions(t *gomkore.Trace, g *gomkore.Goal, n int)

func (WriteTracer) GoalUpToDate added in v0.11.13 

func (tr WriteTracer) GoalUpToDate(t *gomkore.Trace, g *gomkore.Goal)

func (WriteTracer) Info added in v0.11.13 

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

func (*WriteTracer) ParseLevelFlag added in v0.11.14 

func (tr *WriteTracer) ParseLevelFlag(f string) error

func (WriteTracer) RemoveArtefact added in v0.11.13 

func (tr WriteTracer) RemoveArtefact(t *gomkore.Trace, g *gomkore.Goal)

func (WriteTracer) RunAction added in v0.11.13 

func (tr WriteTracer) RunAction(t *gomkore.Trace, a *gomkore.Action)

func (WriteTracer) RunImplicitAction added in v0.11.13 

func (tr WriteTracer) RunImplicitAction(t *gomkore.Trace, _ *gomkore.Action)

func (WriteTracer) ScheduleNotPremises added in v0.11.13 

func (tr WriteTracer) ScheduleNotPremises(t *gomkore.Trace, a *gomkore.Action, res *gomkore.Goal)

func (WriteTracer) ScheduleOutdated added in v0.11.13 

func (tr WriteTracer) ScheduleOutdated(t *gomkore.Trace, a *gomkore.Action, res, pre *gomkore.Goal)

func (WriteTracer) SchedulePreTimeZero added in v0.11.13 

func (tr WriteTracer) SchedulePreTimeZero(t *gomkore.Trace, a *gomkore.Action, res, pre *gomkore.Goal)

func (WriteTracer) ScheduleResTimeZero added in v0.11.13 

func (tr WriteTracer) ScheduleResTimeZero(t *gomkore.Trace, a *gomkore.Action, res *gomkore.Goal)

func (WriteTracer) SetupActionEnv added in v0.11.14 

func (tr WriteTracer) SetupActionEnv(t *gomkore.Trace, env *gomkore.Env) (*gomkore.Env, error)

func (WriteTracer) StartProject added in v0.11.13 

func (tr WriteTracer) StartProject(t *gomkore.Trace, p *gomkore.Project, activity string)

func (WriteTracer) Warn added in v0.11.13 

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

Source Files

View all Source files

Directories

Path Synopsis
This is an example gomk project that offers you a practical approach.
 This is an example gomk project that offers you a practical approach.
cmd/bar
cmd/foo
internal
Package gomkore implements the core model of gomk for the representation of buildable projects.
 Package gomkore implements the core model of gomk for the representation of buildable projects.

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.