Documentation
¶
Index ¶
- Constants
- Variables
- func RegisterExecDriver(name string, factory RunnerFactory)
- func RelPath(source, path string) string
- func ValidateName(name string) error
- func ValidateProjectName(name string) error
- type BackgroundRunner
- type CommonSettings
- type EventHandler
- type EvtAbortRequested
- type EvtTaskAbort
- type EvtTaskActivated
- type EvtTaskFinish
- type EvtTaskOutput
- type EvtTaskStart
- type EvtTaskStop
- type ExecPlan
- func (p *ExecPlan) AddTarget(t *Target) (*Task, bool)
- func (p *ExecPlan) Execute(abortCh <-chan os.Signal) error
- func (p *ExecPlan) GenerateSummary() (err error)
- func (p *ExecPlan) Logf(fmt string, args ...interface{})
- func (p *ExecPlan) OnEvent(handler EventHandler) *ExecPlan
- func (p *ExecPlan) Rebuild(targets ...string) *ExecPlan
- func (p *ExecPlan) Require(targets ...string) error
- func (p *ExecPlan) Skip(targets ...string) *ExecPlan
- type ExecSummary
- type File
- type Project
- func (p *Project) DebugLogFile() string
- func (p *Project) Finalize() error
- func (p *Project) GetSettings(v interface{}) error
- func (p *Project) GetSettingsIn(name string, v interface{}) error
- func (p *Project) Glob(pattern string) (paths []string, err error)
- func (p *Project) IsCommand(name string) bool
- func (p *Project) Load(path string) (*File, error)
- func (p *Project) LoadRcFiles() error
- func (p *Project) MergeSettingsFlat(flat map[string]interface{}) error
- func (p *Project) Plan() *ExecPlan
- func (p *Project) Resolve() error
- func (p *Project) Summary() (ExecSummary, error)
- func (p *Project) SummaryFile() string
- func (p *Project) TargetNames() []string
- func (p *Project) TargetNamesMatch(pattern string) (names []string, err error)
- func (p *Project) WorkPath() string
- func (p *Project) WrapperTarget() *Target
- type Runner
- type RunnerFactory
- type Settings
- type Target
- func (t *Target) AddDep(dep *Target)
- func (t *Target) BaseDir(dirs ...string) string
- func (t *Target) BuildWatchList() (list WatchList)
- func (t *Target) CommonSettings() (settings CommonSettings, err error)
- func (t *Target) Errorf(format string, args ...interface{}) error
- func (t *Target) GetExt(v interface{}) error
- func (t *Target) GetSettings(name string, v interface{}) (err error)
- func (t *Target) GetSettingsWithExt(name string, v interface{}) (err error)
- func (t *Target) Initialize(name string, project *Project)
- func (t *Target) IsTransit() bool
- func (t *Target) ProjectPath(path string) string
- func (t *Target) WorkingDir(dirs ...string) string
- type TargetNameMap
- type Task
- func (t *Task) Abort(abandon bool, signal os.Signal)
- func (t *Task) BuildSuccessMark() error
- func (t *Task) CalcSuccessMark() bool
- func (t *Task) CreateRunner() (Runner, error)
- func (t *Task) Duration() time.Duration
- func (t *Task) EnvVars() []string
- func (t *Task) IsActivated() bool
- func (t *Task) IsBackground() bool
- func (t *Task) Name() string
- func (t *Task) Project() *Project
- func (t *Task) Run() (result TaskResult, err error)
- func (t *Task) Stop() (err error)
- func (t *Task) Summary() *TaskSummary
- func (t *Task) ValidateArtifacts() bool
- func (t *Task) WorkingDir(dirs ...string) string
- func (t *Task) Write(p []byte) (int, error)
- type TaskResult
- type TaskState
- type TaskSummary
- type WatchItem
- type WatchList
Constants ¶
const ( // Format is the supported format Format = "hypermake.v0" // RcFile is the filename of local setting file to override some settings RcFile = ".hmakerc" // WorkFolder is the name of project WorkFolder WorkFolder = ".hmake" // SummaryFileName is the filename of summary SummaryFileName = "hmake.summary.json" // LogFileName is the filename of hmake debug log LogFileName = "hmake.debug.log" // WrapperMagic is the magic string at the beginning of the file WrapperMagic = "#hmake-wrapper" // WrapperName is project name for wrapped project WrapperName = "wrapper" // WrapperDesc is project description for wrapped project WrapperDesc = "wrapped HyperMake project" // MaxNameLen restricts the maximum length of project/target name MaxNameLen = 1024 )
const (
// SettingExecDriver is the property name of exec-driver
SettingExecDriver = "exec-driver"
)
Variables ¶
var ( // ErrMissingArtifacts indicates some of the artifacts not found ErrMissingArtifacts = fmt.Errorf("missing artifacts") // DefaultExecDriver specify the default exec-driver to use DefaultExecDriver string )
var ( // RootFile is hmake filename sits on root RootFile = "HyperMake" // ErrUnsupportedFormat indicates the file is not recognized ErrUnsupportedFormat = fmt.Errorf("unsupported format") // ErrNameMissing indicates name is required, but missing ErrNameMissing = fmt.Errorf("name is required") // ErrNameTooLong indicates the length of name exceeds MaxNameLen ErrNameTooLong = fmt.Errorf("name is too long") // ErrNameFirstChar indicates the first char in name is illegal ErrNameFirstChar = fmt.Errorf("name must start from a letter or an underscore") // ErrProjectNameMissing indicates project name is absent ErrProjectNameMissing = fmt.Errorf("project name is required") // ErrWrapperImageMissing indicates image name is missing ErrWrapperImageMissing = fmt.Errorf("image name missing after " + WrapperMagic) )
Functions ¶
func RegisterExecDriver ¶
func RegisterExecDriver(name string, factory RunnerFactory)
RegisterExecDriver registers a runner
func ValidateName ¶ added in v1.1.0
ValidateName checks if a name is legal: starting from a letter/underscore and following characters are from letters/digits/underscore/dash/dot
func ValidateProjectName ¶ added in v1.1.0
ValidateProjectName validates if project name is legal
Types ¶
type BackgroundRunner ¶ added in v1.3.0
type BackgroundRunner interface { // Stop stops the background task Stop() error }
BackgroundRunner starts the task and runs in background
type CommonSettings ¶ added in v1.1.0
type CommonSettings struct { DefaultTargets []string `map:"default-targets"` ExecTarget string `map:"exec-target"` ExecShell string `map:"exec-shell"` }
CommonSettings are well known settings
type EventHandler ¶
type EventHandler func(event interface{})
EventHandler receives event notifications during execution of plan
type EvtAbortRequested ¶
EvtAbortRequested is emitted when abort is requested over all running tasks
type EvtTaskAbort ¶
EvtTaskAbort is emitted when task is being aborted
type EvtTaskActivated ¶
type EvtTaskActivated struct {
Task *Task
}
EvtTaskActivated is emitted when task is queued
type EvtTaskFinish ¶
type EvtTaskFinish struct {
Task *Task
}
EvtTaskFinish is emitted when task finishes
type EvtTaskOutput ¶
EvtTaskOutput is emitted when output is received
type EvtTaskStart ¶
type EvtTaskStart struct {
Task *Task
}
EvtTaskStart is emitted before task gets run
type EvtTaskStop ¶ added in v1.3.0
type EvtTaskStop struct {
Task *Task
}
EvtTaskStop is emitted when request a background task to stop
type ExecPlan ¶
type ExecPlan struct { // Project is the wrapped project Project *Project // Tasks are the tasks need execution Tasks map[string]*Task // Env is pre-defined environment variables Env map[string]string // WorkPath is full path to hmake state dir ProjectDir/.hmake WorkPath string // MaxConcurrency defines maximum number of tasks being executed in parallel // if it's 0, the number of CPU cores are counted MaxConcurrency int // RebuildAll force rebuild everything regardless of success mark RebuildAll bool // RebuildTargets specify targets to rebuild regardless of success mark RebuildTargets map[string]bool // SkippedTargets specify targets to be marked as Skipped SkippedTargets map[string]bool // RequiredTargets are names of targets explicitly required RequiredTargets []string // RunnerFactory specifies the custom runner factory RunnerFactory RunnerFactory // DebugLog enables logging debug info into .hmake/hmake.debug.log DebugLog bool // Dryrun will skip the actual execution of target, just return success DryRun bool // WaitingTasks are tasks in waiting state WaitingTasks map[string]*Task // QueuedTasks are tasks in Queued state QueuedTasks []*Task // RunningTasks are tasks in Running state RunningTasks map[string]*Task // FinishedTasks are tasks in finished state FinishedTasks []*Task // EventHandler handles the events during execution EventHandler EventHandler // Summary is the report of all executed targets Summary ExecSummary // contains filtered or unexported fields }
ExecPlan describes the plan for execution
func NewExecPlan ¶
NewExecPlan creates an ExecPlan for a Project
func (*ExecPlan) GenerateSummary ¶
GenerateSummary dumps summary to summary file
func (*ExecPlan) OnEvent ¶
func (p *ExecPlan) OnEvent(handler EventHandler) *ExecPlan
OnEvent subscribes the events
type ExecSummary ¶ added in v1.1.0
type ExecSummary []*TaskSummary
ExecSummary is the summary of plan execution
func (ExecSummary) ByTarget ¶ added in v1.1.0
func (s ExecSummary) ByTarget(target string) *TaskSummary
ByTarget find target execution summary by target name
type File ¶
type File struct { // Format indicates file format Format string `map:"format"` // Name is name of the project Name string `map:"name"` // Desc is description of the project Desc string `map:"description"` // Targets are targets defined in current file Targets map[string]*Target `map:"targets"` // Commands are targets used as commands Commands map[string]*Target `map:"commands"` // Settings are properties Settings Settings `map:"settings"` // Local are properties only applied to file Local Settings `map:"local"` // Includes are patterns for sourcing external files Includes []string `map:"includes"` // Source is the relative path to the project Source string `map:"-"` // WrapperTarget specifies the default target in wrapper mode WrapperTarget string `map:"-"` }
File defines the content of HyperMake or .hmake file
type Project ¶
type Project struct { // Name is name of the project Name string // BaseDir is the root directory of project BaseDir string // LaunchPath is relative path under BaseDir where hmake launches LaunchPath string // MasterFile is the file with everything merged MasterFile File // All loaded make files Files []*File // Tasks are built from resolved targets Targets TargetNameMap }
Project is the world view of hmake
func LoadProject ¶
LoadProject locates, resolves and finalizes project
func LoadProjectFrom ¶
LoadProjectFrom locates, resolves and finalizes project from startDir
func LocateProject ¶
LocateProject creates a project by locating the root file
func LocateProjectFrom ¶
LocateProjectFrom creates a project by locating the root file from startDir
func (*Project) DebugLogFile ¶
DebugLogFile returns the fullpath to debug log file
func (*Project) Finalize ¶
Finalize builds up the relationship between targets and settings and also verifies any cyclic dependencies
func (*Project) GetSettings ¶
GetSettings maps settings into provided variable
func (*Project) GetSettingsIn ¶
GetSettingsIn maps settings[name] into provided variable
func (*Project) LoadRcFiles ¶
LoadRcFiles load .hmakerc files inside project directories
func (*Project) MergeSettingsFlat ¶
MergeSettingsFlat merges settings from a flat key/value map
func (*Project) Summary ¶ added in v1.1.0
func (p *Project) Summary() (ExecSummary, error)
Summary loads the execution summary
func (*Project) SummaryFile ¶
SummaryFile returns the fullpath to summary file
func (*Project) TargetNames ¶
TargetNames returns sorted target names
func (*Project) TargetNamesMatch ¶
TargetNamesMatch returns sorted and matched target names
func (*Project) WrapperTarget ¶ added in v1.1.1
WrapperTarget returns the wrapper target if in wrapper mode
type Runner ¶
type Runner interface { // Run executes the task Run(<-chan os.Signal) (TaskResult, error) // Signature generates the signature of task for change detection Signature() string // ValidateArtifacts validates task specific artifacts which may not be files ValidateArtifacts() bool }
Runner is the handler execute a target
type RunnerFactory ¶
RunnerFactory creates a runner from a task
type Settings ¶
type Settings map[string]interface{}
Settings applies to targets
type Target ¶
type Target struct { Name string `map:"name"` Desc string `map:"description"` Before []string `map:"before"` After []string `map:"after"` ExecDriver string `map:"exec-driver"` WorkDir string `map:"workdir"` Watches []string `map:"watches"` Always bool `map:"always"` Artifacts []string `map:"artifacts"` Ext map[string]interface{} `map:"*"` Project *Project `map:"-"` File *File `map:"-"` Command bool `map:"-"` Exec bool `map:"-"` Args []string `map:"-"` Depends TargetNameMap `map:"-"` Activates TargetNameMap `map:"-"` }
Target defines a build target
func (*Target) BaseDir ¶ added in v1.1.0
BaseDir returns the project relative path relative to file defining the target
func (*Target) BuildWatchList ¶
BuildWatchList collects current state of all watched items
func (*Target) CommonSettings ¶ added in v1.1.0
func (t *Target) CommonSettings() (settings CommonSettings, err error)
CommonSettings retrieve common settings from target local and project
func (*Target) GetSettings ¶
GetSettings extracts the value from settings stack
func (*Target) GetSettingsWithExt ¶
GetSettingsWithExt extracts the value from Ext and settings stack
func (*Target) Initialize ¶
Initialize prepare fields in target
func (*Target) ProjectPath ¶
ProjectPath translate a source relative path to project relative path
func (*Target) WorkingDir ¶
WorkingDir returns the project relative working dir for executing the target
type TargetNameMap ¶
TargetNameMap is targets mapping by name
func (TargetNameMap) Add ¶
func (m TargetNameMap) Add(t *Target) error
Add adds a target to name map
func (TargetNameMap) BuildDeps ¶
func (m TargetNameMap) BuildDeps() error
BuildDeps builds direct depends and activates
func (TargetNameMap) CheckCyclicDeps ¶
func (m TargetNameMap) CheckCyclicDeps() error
CheckCyclicDeps detects cycles in depenencies
func (TargetNameMap) CompleteName ¶
func (m TargetNameMap) CompleteName(name string) ([]string, error)
CompleteName resolve pattern as a single name
func (TargetNameMap) CompleteNames ¶
func (m TargetNameMap) CompleteNames(in []string, errs *errors.AggregatedError) (out []string)
CompleteNames resolves pattern in name list
type Task ¶
type Task struct { // Plan is ExecPlan owns the task Plan *ExecPlan // Target is wrapped target Target *Target // Depends is the tasks being depended on // The task is activated when depends is empty Depends map[string]*Task // State indicates task state State TaskState // Result indicates the result of the task Result TaskResult // Error represents any error happened during execution Error error // StartTime StartTime time.Time // FinishTime FinishTime time.Time // contains filtered or unexported fields }
Task is the execution state of a target
func (*Task) BuildSuccessMark ¶
BuildSuccessMark checks if the task can be skipped
func (*Task) CalcSuccessMark ¶
CalcSuccessMark calculates the watchlist digest and checks if the task can be skipped
func (*Task) CreateRunner ¶ added in v1.1.0
CreateRunner creates a runner for current task
func (*Task) IsActivated ¶
IsActivated indicates the task is ready to run
func (*Task) IsBackground ¶ added in v1.3.0
IsBackground determine if task is running in background
func (*Task) Summary ¶
func (t *Task) Summary() *TaskSummary
Summary generates summary info of the task
func (*Task) ValidateArtifacts ¶ added in v1.1.0
ValidateArtifacts verifies if artifacts are present
func (*Task) WorkingDir ¶
WorkingDir is absolute path of working dir to execute the task
type TaskResult ¶
type TaskResult int
TaskResult indicates the result of task execution
const ( Unknown TaskResult = iota Started Success Skipped Failure Aborted )
Task results
func (TaskResult) IsOK ¶
func (r TaskResult) IsOK() bool
IsOK indicates the result is positive Started/Success/Skipped
func (*TaskResult) MarshalJSON ¶ added in v1.1.0
func (r *TaskResult) MarshalJSON() ([]byte, error)
MarshalJSON implements Marshaller
func (TaskResult) String ¶
func (r TaskResult) String() string
func (*TaskResult) UnmarshalJSON ¶ added in v1.1.0
func (r *TaskResult) UnmarshalJSON(data []byte) error
UnmarshalJSON implements Unmarshaller
type TaskState ¶
type TaskState int
TaskState indicates the state of task
func (*TaskState) MarshalJSON ¶ added in v1.1.0
MarshalJSON implements Marshaller
func (*TaskState) UnmarshalJSON ¶ added in v1.1.0
UnmarshalJSON implements Unmarshaller
type TaskSummary ¶ added in v1.1.0
type TaskSummary struct { Target string `json:"target"` State TaskState `json:"state"` StartAt time.Time `json:"start-at,omitempty"` FinishAt time.Time `json:"finish-at,omitempty"` Result TaskResult `json:"result"` Error string `json:"error,omitempty"` }
TaskSummary is the execution summary of the task