README
¶
About
Go Build Toolbox is a very simple toolbox providing some small utility functions that make it easy to write golang files dedicated to building.
It's purpose is to eliminate any build tool dependencies in your project except for go compiler itself.
Including make.
That's why Go Build Toolbox does not have any command line utility, as it's not meant to be ran as one.
Writing a build script in go is quite simple, the only thing really missing is running tasks in parallel and task dependency
management similar to make. And that's pretty much the main thing this toolbox aims to provide, along with few convienience functions.
Example
For instance if we have a simple project that would contain Makefile like:
all: app
go_files := $(shell find . -name '*.go')
app: $(go_files)
go build -o app main.go
Could be accomplished with:
// +build make
package main
import (
"github.com/Dennor/gbtb"
)
func main() {
gbtb.MustRun(
gbtb.Task{
Name: "all",
Dependencies: gbtb.StaticDependencies{"app"},
},
gbtb.Task{
Name: "app",
Job: gbtb.GoBuild("main.go", "-o", "app"),
Dependencies: gbtb.GlobFiles("**/*.go"),
},
)
}
Non-goals
- Make syntax shorter than
Makefile. While it would be nice to add as many convienience functions as possible to shorten the build files, that's not the goal of this project. Atleast not a main one. If anyone writes a convienience function and makes a PR with it, I'll be happy to include it, but unless I personally need something, I will not be adding new functionalities. - Make a tool out of it. I do not want it to become another tool that you need to install (even through go get). Your main function should be enough.
Documentation
¶
Index ¶
- Variables
- func FlagsInit(flagSet *flag.FlagSet)
- func MustOutput(cmd string, args ...string) []byte
- func MustOutputPipe(cmds ...*exec.Cmd) []byte
- func MustRun(tasks ...TaskGetter)
- func Output(cmd string, args ...string) ([]byte, error)
- func OutputPipe(cmds ...*exec.Cmd) ([]byte, error)
- func PipeCommands(cmds ...*exec.Cmd) (err error)
- func PipeCommandsContext(ctx context.Context, cmds ...*exec.Cmd) (err error)
- func Run(tasks ...TaskGetter) error
- func RunCommand(cmd string, args ...string) error
- func RunStoppable(stop chan struct{}, name string, args ...string) error
- func StoppableCommandJob(cmd string, args ...string) func(chan struct{}) error
- type Dependencies
- type DependenciesList
- type DependencyFunc
- type Job
- type LongRunning
- type ModTime
- type MultiTargetDependencies
- type MultiTargetDependencyFunc
- type MultiTargetDependencyList
- type MultiTargetJob
- type MultiTargetModTime
- type MultiTargetTask
- type Notify
- type NotifyLongRunning
- type Runner
- type StaticDependencies
- type StoppableLongRunning
- type StringFormatWithName
- type Task
- type TaskGetter
- type TaskLike
- type Tasks
Constants ¶
This section is empty.
Variables ¶
var ( // Jobs is a global defining how many jobs can be run in parallel at once Jobs = runtime.NumCPU() )
Functions ¶
func FlagsInit ¶
FlagsInit adds gbtb flags to flagSet, if flagSet is nil, flags are added to flag.CommandLine
func MustOutput ¶
MustOutput runs a command and returns it's stdout panicing on error
func MustOutputPipe ¶
MustOutputPipe runs a command and returns it's stdout panicing on error
func MustRun ¶
func MustRun(tasks ...TaskGetter)
MustRun run the tasks using command line args, exits process on error
func OutputPipe ¶
OutputPipe runs a command pipe and returns the stdout of last command panicing on error
func PipeCommands ¶
PipeCommands check out documentation for PipeCommandsContext
func PipeCommandsContext ¶
PipeCommandsContext runs a list of commands piping input from previous command to output of the following one. If first command in a list has Stdin set, it will be used as a Stdin for the first command in the pipe. Otherwise reader that will always return io.EOF will be used. If caller provides a custom input, it is caller's responsibility to make sure that it will end reading with io.EOF, at some point, otherwise this function will block. If last command in a list has Stdout set, it will be used as a Stdout for the last command in the pipe, otherwise os.Stdout is used For each command stderr is piped to os.Stderr, unless command has non nil Stderr If any proccess in the pipe finished with an error, all proccesses that did not get waited on will be killed and function will return that error. If more than one proccess finishes with an error, it is not guaranteed which one will be returned except for the fact that atleast one will be returned Function appends current environment flags to command without overriding those already defined. On context done function attempts to terminate proccess with os.Interrupt, if process does not terminate in 10 seconds, it gets killed.
func RunCommand ¶
RunCommand runs a single command. For more information check out PipeCommands
func RunStoppable ¶
RunStoppable Runs a command with an ability to stop it
func StoppableCommandJob ¶
StoppableCommandJob is a convienience function that runs a stoppable job
Types ¶
type Dependencies ¶
Dependencies is an interface providing access to task dependecies
type DependenciesList ¶
type DependenciesList []Dependencies
DependenciesList is a helper to easly build multiple dependencies for target
func NewDependenciesList ¶
func NewDependenciesList(d Dependencies, nd ...Dependencies) DependenciesList
NewDependenciesList returns a new dependency chain
func (DependenciesList) Append ¶
func (dc DependenciesList) Append(d ...Dependencies) DependenciesList
Append a new dependency to chain
func (DependenciesList) Get ¶
func (dc DependenciesList) Get() ([]string, error)
Get returns evaluated list of dependencies for a target
func (DependenciesList) TargetDependencies ¶
func (dc DependenciesList) TargetDependencies(string) Dependencies
type DependencyFunc ¶
DependencyFunc is a helper type useful for constructing dependencies only when tasked is executed
func GlobFiles ¶
func GlobFiles(pattern string) DependencyFunc
GlobFiles returns a glob dependency supporting double start (**) matching
func (DependencyFunc) Get ¶
func (d DependencyFunc) Get() ([]string, error)
func (DependencyFunc) TargetDependencies ¶
func (d DependencyFunc) TargetDependencies(string) Dependencies
type Job ¶
type Job func() error
Job is an operation in build
func CommandJob ¶
CommandJob is a convienience function that simply runs a command as a job
func CommandJobPipe ¶
CommandJobPipe is a convienience function that runs a pipe of commands as a job
type LongRunning ¶
type LongRunning struct {
// Name of long running target
Name string
// Dependencies of long running target
Dependencies Dependencies
// Job is stoppable job for long running task
Job func(chan struct{}) error
}
LongRunning adds support for long running tasks stopped on os.Interrupt
func (*LongRunning) DependsOn ¶
func (l *LongRunning) DependsOn() Dependencies
DependsOn for long running task
func (*LongRunning) GetNames ¶
func (l *LongRunning) GetNames() []string
func (*LongRunning) GetTask ¶
func (l *LongRunning) GetTask(name string) TaskLike
type ModTime ¶
ModTime returns the last time artifacts resulting from task were modified
func CommandModTime ¶
CommandModTime is a convienience function that simply runs a command which must only return a time with given format
type MultiTargetDependencies ¶
type MultiTargetDependencies interface {
TargetDependencies(string) Dependencies
}
MultiTargetDependencies is an interface providing access to MultiTargetTask dependecies
type MultiTargetDependencyFunc ¶
type MultiTargetDependencyFunc func(string) Dependencies
MultiTargetDependencyFunc is an convienience type implementing MultiTargetDependencies
func (MultiTargetDependencyFunc) TargetDependencies ¶
func (m MultiTargetDependencyFunc) TargetDependencies(name string) Dependencies
type MultiTargetDependencyList ¶
type MultiTargetDependencyList []MultiTargetDependencies
MultiTargetDependencyList is a static list of multi target dependencies
func (MultiTargetDependencyList) TargetDependencies ¶
func (d MultiTargetDependencyList) TargetDependencies(name string) Dependencies
type MultiTargetModTime ¶
MultiTargetModTime for a multitarget task
type MultiTargetTask ¶
type MultiTargetTask struct {
Names []string
Job MultiTargetJob
ModTime MultiTargetModTime
Dependencies MultiTargetDependencies
// contains filtered or unexported fields
}
MultiTargetTask is a group targets sharing similar tasks
func (*MultiTargetTask) GetNames ¶
func (m *MultiTargetTask) GetNames() []string
GetNames defined for MultiTargetTask
func (*MultiTargetTask) GetTask ¶
func (m *MultiTargetTask) GetTask(name string) TaskLike
GetTask for a name
type Notify ¶
type Notify struct {
// Name of notify task
Name string
// Job is a name of task to run on change
Job string
Task TaskLike
}
Notify task is a blocking task that runs named task when change in file system is detected
func (*Notify) DependsOn ¶
func (n *Notify) DependsOn() Dependencies
type NotifyLongRunning ¶
type NotifyLongRunning struct {
// Name of long running target
Name string
// Dependencies of long running target
Dependencies Dependencies
// Job is stoppable job for long running task
Job func(chan struct{}) error
}
NotifyLongRunning start a long running task and restarts if there's a change detected in file system
func (*NotifyLongRunning) DependsOn ¶
func (l *NotifyLongRunning) DependsOn() Dependencies
DependsOn for long running task
func (*NotifyLongRunning) GetNames ¶
func (l *NotifyLongRunning) GetNames() []string
func (*NotifyLongRunning) GetTask ¶
func (l *NotifyLongRunning) GetTask(name string) TaskLike
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner executes jobs in parallel
func (*Runner) Put ¶
Put queues a job for runner. Return error is the same as an error returned by f. User must ensure that all Put calls finished before calling Stop
type StaticDependencies ¶
type StaticDependencies []string
StaticDependencies is a list of strings naming dependencies directly
func (StaticDependencies) Get ¶
func (d StaticDependencies) Get() ([]string, error)
func (StaticDependencies) TargetDependencies ¶
func (d StaticDependencies) TargetDependencies(string) Dependencies
type StoppableLongRunning ¶
type StoppableLongRunning struct {
// Name of long running target
Name string
// Dependencies of long running target
Dependencies Dependencies
// Job is stoppable job for long running task
Job func(chan struct{}) error
Stop chan struct{}
}
StoppableLongRunning adds support for long running stoppable tasks
func (*StoppableLongRunning) DependsOn ¶
func (l *StoppableLongRunning) DependsOn() Dependencies
DependsOn for long running task
func (*StoppableLongRunning) GetNames ¶
func (l *StoppableLongRunning) GetNames() []string
func (*StoppableLongRunning) GetTask ¶
func (l *StoppableLongRunning) GetTask(name string) TaskLike
func (*StoppableLongRunning) Reset ¶
func (l *StoppableLongRunning) Reset()
Reset the long running task
type StringFormatWithName ¶
type StringFormatWithName []string
func (StringFormatWithName) TargetDependencies ¶
func (m StringFormatWithName) TargetDependencies(name string) Dependencies
type Task ¶
type Task struct {
// Name of a task, with behaviour similar to make.
// If a file matching task name exists, it is assumed that it's a result of this
// task is that file, and like in make, mod times of resulting file
// and it's dependencies will be compared.
Name string
// List of dependencies. A dependency can be a task name or a file, checked in that
// order. If there's no task named as dependency or no file matching that name
// build task will fail
Dependencies Dependencies
// Job ran by task
Job Job
// ModTime is a function that allows user to override default behaviour
// testing when was the target updated last time. For example docker image
// creation date. If not provided, a mod time of a file with the same
// name as task name is used.
ModTime ModTime
// contains filtered or unexported fields
}
Task in build
func (*Task) DependsOn ¶
func (t *Task) DependsOn() Dependencies
type TaskGetter ¶
TaskGetter interface
type Tasks ¶
type Tasks []TaskGetter
Tasks is a list of tasks defined by build
func (Tasks) Do ¶
Do executes a list of tasks out of all tasks defined, if no task is provided, just like make, execute the first task.
func (Tasks) MustRun ¶
func (tasks Tasks) MustRun()
MustRun gbtb with command line arguments, if there's an error exits process with status 1
func (Tasks) MustRunWithFlags ¶
MustRunWithFlags adds gbtb to flagSet, parses flags and runs with them. If flagSet nil fall back to flag.CommandLine, if there's an error process exits with status 1
Source Files
Directories