Quick Start

System requirements

dawn runs anywhere Go is supported, including (but not limited to) macOS, Linux, and Windows.

Install dawn

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

macOS/LinuxWindows

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

Alternatively, dawn may be installed manually using go install:

go install github.com/pgavlin/dawn@latest

Shell completion

dawn has built-in support for shell completions for Bash, Zsh, fish, and PowerShell. To enable shell completions, run dawn completions and follow the instructions for your shell. dawn provides completions for subcommands, flags, and targets.

Create a new project

During this quick start, you will create a simple Go application. In addition to dawn, you will need to install Go.

Once you have installed the prerequisites, create a new directory to hold your project and run dawn init:

..tabs:

.. code-tab:: bash macOS/Linux

    mkdir hello-dawn
    cd hello-dawn
    dawn init

.. code-tab:: powershell Windows

    mkdir hello-dawn
    cd hello-dawn
    dawn init

Create a simple Go command-line tool

Create a new Go module in the current directory:

go mod init hello-dawn

Then copy the code below into a file named main.go:

package main

import "fmt"

func main() {
    fmt.Println("Hello, dawn!")
}

Write your first build target

Copy the code below into a file named BUILD.dawn:

@target(sources=["main.go", "go.mod"], generates=["hello-dawn"], default=True)
def hello_dawn():
    """
    Builds the hello-dawn executable.
    """

    sh.exec("go build -o hello-dawn .")

This code defines a single target, //:hello_dawn, that will be run if any ofthe following conditions are true:

• the file main.go changes

• the file go.mod changes

• the file hello-dawn does not exist

• the hello_dawn function’s environment–i.e. its code and the values of its referenced variables–changes

When the target is run, the body of the hello_dawn function will execute and run go build to build the hello-dawn binary.

Run a build

Build the project’s default target, hello_dawn:

dawn
[source://:go.mod] done
[source://:main.go] done
[//:hello_dawn] done
[//:default] done

This will produce an executable named hello-dawn in the project’s directory. Running the hello-dawn executable will print Hello, dawn!:

./hello-dawn
Hello, dawn!

Now, try building the project’s default target again:

dawn

This should produce no output, as nothing has changed since the last time the target was built.

Explore your project

dawn provides powerful tools for exploring your project. To see all of your project’s targets, run dawn list targets:

dawn list targets
//:default    Builds the hello-dawn executable.
//:hello_dawn Builds the hello-dawn executable.

To see the sources and targets that the //:hello_dawn target depends on, run dawn list depends //:hello_dawn:

dawn list depends //:hello_dawn
source://:go.mod
source://:main.go

To launch the REPL and interactively explore your project, run dawn repl:

dawn repl
>>>

Inside the REPL, call targets() to list your project’s targets:

>>> targets()
[//:default, //:hello_dawn]

Then, call run(“//:hello_dawn”) to build the //:hello_dawn target:

>>> run("//:hello_dawn")
[//:hello_dawn] done
>>>

Exit the REPL by pressing Ctrl+D to send an EOF:

>>> ^D

Make a change

Change the contents of the file main.go to the following:

package main

import "fmt"

func main() {
    fmt.Println("Hello again, dawn!")
}

Now, rebuild the project’s default target:

dawn
[source://:main.go] done
[//:hello_dawn] done
[//:default] done

Because the contents of main.go changed, dawn re-ran the //:hello_dawn target and built a new version of the hello-dawn executable. Try running hello-dawn:

./hello-dawn
Hello again, dawn!

Watch a file for changes

In a new terminal, navigate to your project’s directory and run dawn watch:

dawn watch

This command will watch the project’s directory and rebuild the default target any time a file is changed, created, or deleted. Change the contents of main.go back to the original:

package main

import "fmt"

func main() {
    fmt.Println("Hello, dawn!")
}

When you save the file, you should see the following output from dawn watch:

[source://:main.go] done
[//:hello_dawn] done
[//:default] done

Because main.go’s contents changed, dawn rebuilt the default target.

Next steps

Now that you’ve explored the basic capabilities of dawn, you can read more about the core concepts, check out the module reference, and get to work authoring your builds. Have fun!