dawn

README

##################################
☀️ dawn: Pragmatic Polyglot Builds
##################################

.. meta::
   :description lang=en: Build multi-language software projects without sacrificing productivity.

.. image:: https://readthedocs.org/projects/dawn-build/badge/?version=latest&style=flat
   :target: https://dawn-build.io
   :alt: Read the Docs
.. image:: https://pkg.go.dev/badge/github.com/pgavlin/dawn
   :target: https://pkg.go.dev/github.com/pgavlin/dawn
   :alt: pkg.go.dev
.. image:: https://codecov.io/gh/pgavlin/dawn/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/pgavlin/dawn
   :alt: Code Coverage
.. image:: https://github.com/pgavlin/dawn/workflows/Test/badge.svg
   :target: https://github.com/pgavlin/dawn/actions?query=workflow%3ATest
   :alt: Build Status

dawn_ helps you modernize your build without leaving your existing ecosystems behind.
The IDE integrations, refactoring tools, etc. that you depend on will continue to work,
with many of the benefits of a modern build system:

- Content-based checks for out-of-date targets
- Parallel builds by default
- Build files written in Starlark, a dialect of Python
- Watch mode to automatically rebuild when files change
- Performance profiling for builds
- Cross-platform tooling
- ...and more

Installation
============

The simplest way to install dawn_ is using the installation script:

.. tabs::

   .. code-tab:: bash macOS/Linux

        curl -fsSL https://get.dawn-build.io | sh

   .. code-tab:: powershell Windows

        @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; iex ((New-Object System.Net.WebClient).DownloadString('https://get.dawn-build.io/install.ps1'))" && SET "PATH=%PATH%;%USERPROFILE%\.dawn\bin"

Alternatively, dawn_ may be installed manually using `go install`:

.. code-block:: bash

   go install github.com/pgavlin/dawn@latest

.. _dawn: https://dawn-build.io

Documentation

Index

• Variables
• func CurrentModule(thread *starlark.Thread) (*label.Label, bool)
• func DocSummary(t Target) string
• func IsSource(l *label.Label) bool
• func IsTarget(l *label.Label) bool
• type Events
• type Flag
  • func (f *Flag) Attr(name string) (starlark.Value, error)
  • func (f *Flag) AttrNames() []string
  • func (f *Flag) Doc() string
  • func (f *Flag) Freeze()
  • func (f *Flag) Hash() (uint32, error)
  • func (f *Flag) String() string
  • func (f *Flag) Truth() starlark.Bool
  • func (f *Flag) Type() string
• type LoadOptions
• type Project
  • func Load(root string, options *LoadOptions) (proj *Project, err error)
  • func (proj *Project) Flag(name string) (*Flag, error)
  • func (proj *Project) Flags() []*Flag
  • func (proj *Project) GC() error
  • func (proj *Project) LoadTarget(rawlabel string) (runner.Target, error)
  • func (proj *Project) REPLEnv(stdout io.Writer, pkg *label.Label) (thread *starlark.Thread, globals starlark.StringDict)
  • func (proj *Project) Reload() (err error)
  • func (proj *Project) Run(label *label.Label, options *RunOptions) error
  • func (proj *Project) Sources() []string
  • func (proj *Project) Target(label *label.Label) (Target, error)
  • func (proj *Project) Targets() []Target
  • func (proj *Project) Watch(label *label.Label) error
• type RunOptions
• type Target
• type TargetSummary
  • func Targets(root string) ([]TargetSummary, error)
• type UnknownTargetError
  • func (e UnknownTargetError) Error() string

Variables

var DiscardEvents = discardEventsT(0)

DiscardEvents is an implementation of Events that discards all events.

Functions

func CurrentModule

func CurrentModule(thread *starlark.Thread) (*label.Label, bool)

func DocSummary

func DocSummary(t Target) string

DocSummary returns a summary of the target's docstring.

func IsSource

func IsSource(l *label.Label) bool

func IsTarget

func IsTarget(l *label.Label) bool

Types

type Events

type Events interface {
	// Print logs a line of output associated with a module or target.
	Print(label *label.Label, line string)

	// ModuleLoading is called when the given module begins loading.
	ModuleLoading(label *label.Label)
	// ModuleLoaded is called when the given module finishes loading successfully.
	ModuleLoaded(label *label.Label)
	// ModuleLoadFailed is called when the given module fails to load.
	ModuleLoadFailed(label *label.Label, err error)
	// LoadDone is called when a project finishes loading.
	LoadDone(err error)

	// TargetUpToDate is called when a target is found to be up-to-date.
	TargetUpToDate(label *label.Label)
	// TargetEvaluating is called when a target begins executing.
	TargetEvaluating(label *label.Label, reason string, diff diff.ValueDiff)
	// TargetFailed is called when a target fails.
	TargetFailed(label *label.Label, err error)
	// TargetSucceeded is called when a target succeeds.
	TargetSucceeded(label *label.Label, changed bool)
	// RunDone is called when a run finishes.
	RunDone(err error)
}

Events allows callers to handle project load and build events.

type Flag

type Flag struct {
	// Name holds the flag's name.
	Name string `json:"name"`
	// Default holds the string representation of the flag's default value.
	Default string `json:"default,omitempty"`
	// FlagType holds the string representation of the flag's type.
	FlagType string `json:"type"`
	// Choices holds string representations of the flag's vlaid values.
	Choices []string `json:"choices,omitempty"`
	// Required is true if the flag is required.
	Required bool `json:"required,omitempty"`
	// Help holds the flag's help message.
	Help string `json:"help,omitempty"`
	// Value holds the flag's value.
	Value starlark.Value `json:"-"`
}

A Flag holds information about a project configuration flag.

func (*Flag) Attr

func (f *Flag) Attr(name string) (starlark.Value, error)

func (*Flag) AttrNames

func (f *Flag) AttrNames() []string

func (*Flag) Doc

func (f *Flag) Doc() string

func (*Flag) Freeze

func (f *Flag) Freeze()

func (*Flag) Hash

func (f *Flag) Hash() (uint32, error)

func (*Flag) String

func (f *Flag) String() string

func (*Flag) Truth

func (f *Flag) Truth() starlark.Bool

func (*Flag) Type

func (f *Flag) Type() string

type LoadOptions

type LoadOptions struct {
	Args   []string
	Events Events

	Builtins starlark.StringDict

	PreferIndex bool
}

type Project

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

A Project is the runtime representation of a dawn project. It is the primary type used to introspect and execute builds.

func Load

func Load(root string, options *LoadOptions) (proj *Project, err error)

func (*Project) Flag

func (proj *Project) Flag(name string) (*Flag, error)

func (*Project) Flags

func (proj *Project) Flags() []*Flag

func (*Project) GC

func (proj *Project) GC() error

func (*Project) LoadTarget

func (proj *Project) LoadTarget(rawlabel string) (runner.Target, error)

LoadTarget implements runner.Host.

func (*Project) REPLEnv

func (proj *Project) REPLEnv(stdout io.Writer, pkg *label.Label) (thread *starlark.Thread, globals starlark.StringDict)

func (*Project) Reload

func (proj *Project) Reload() (err error)

func (*Project) Run

func (proj *Project) Run(label *label.Label, options *RunOptions) error

func (*Project) Sources

func (proj *Project) Sources() []string

func (*Project) Target

func (proj *Project) Target(label *label.Label) (Target, error)

func (*Project) Targets

func (proj *Project) Targets() []Target

func (*Project) Watch

func (proj *Project) Watch(label *label.Label) error

type RunOptions

type RunOptions struct {
	Always bool
	DryRun bool
}

type Target

type Target interface {
	starlark.Value

	// Project returns the project that owns the target.
	Project() *Project
	// Label returns the target's label.
	Label() *label.Label
	// Dependencies returns the labels of the targets the target depends upon.
	Dependencies() []*label.Label
	// Doc returns the target's documentation string.
	Doc() string
	// contains filtered or unexported methods
}

A Target represents a build target within a Project.

type TargetSummary

type TargetSummary struct {
	// Label is the target's label.
	Label *label.Label `json:"label"`
	// Summary is a summary of the target's docstring (as returned by DocSummary(t)).
	Summary string `json:"summary"`
}

A TargetSummary contains summarial information about a build target.

func Targets

func Targets(root string) ([]TargetSummary, error)

Targets returns the targets listed in the index file of the project rooted at the given directory.

type UnknownTargetError

type UnknownTargetError string

An UnknownTargetError is returned by Project.LoadTarget if a referenced target does not exist.

func (UnknownTargetError) Error

func (e UnknownTargetError) Error() string