Packages with dawn

dawn is the package tool for dusk. A dusk package is a git repository, in the Go style: there is no central registry, the source is the package, and the import path tells you where the code lives. This guide covers the three forms an @import can take, the dawn commands, where fetched code lands, and what the tool does not do yet.

The three import forms

An @import is a stdlib dotted path, a local dotted path, or a quoted git path.

@import std.io                            // standard library
@import geometry.shapes                   // local module
@import "github.com/user/repo/module"     // external package, fetched by dawn

The first two resolve without dawn; the compiler handles them on its own. Only the quoted form involves fetching.

Standard library imports

A dotted path into std resolves to a module or to a leaf symbol. Importing a module makes its exported names callable; importing a leaf symbol puts that one name in scope unqualified.

@import std.io                 // module: call std.io.print_line(...)
@import std.io.print_line      // symbol: call print_line(...)

See the stdlib overview for what is in the library, and source files for the full resolution rules.

Local imports

A local dotted path walks the project tree from the importing file: directories first, then files, then symbols. Given a library file in a subdirectory:

geometry/shapes.dusk

// geometry/shapes.dusk
export func area(w: int64, h: int64) -> int64 {
    return w * h
}

a sibling main.dusk imports it by path and calls through the qualified name:

main.dusk

@import std.io
@import geometry.shapes

func main() -> int32 {
    print_int(geometry.shapes.area(3, 4))
    return 0
}

Importing the leaf symbol instead, @import geometry.shapes.area, puts area in scope unqualified. Only exported names cross a file boundary; a private name never leaves its file.

Git imports

An external package uses its git path in quotes.

@import "github.com/user/repo/module"

This fragment does not build on its own: the compiler resolves a git import from the local cache, so the repository has to be fetched first with dawn get (or dawn build / dawn run, which fetch for you). Once the clone is in the cache, you use the module’s exported names the same way as any other import.

How a git path names a package

The first three segments of the quoted path, host/user/repo, name the repository. Everything after them names a module file inside it. So in github.com/user/repo/module, the repository is github.com/user/repo and the module is module.dusk at its root. Resolution falls back to repo.dusk as a leaf, the same way the stdlib resolves a dotted path.

The import string carries no version. dawn fetches the repository, and the dusk compiler resolves the module from the local cache.

The dawn commands

The dawn binary has four commands.

dawn get <file.dusk>     # clone the git packages a file imports into the cache
dawn build <file.dusk>   # fetch packages, then compile
dawn run <file.dusk>     # fetch packages, compile, and run
dawn version

build and run are wrappers: they fetch every imported package, then hand the program to the dusk compiler. You can also fetch with dawn get and call dusk directly.

If you are working from a source checkout of the toolchain, cargo run picks the binary with --bin:

cargo run --bin dawn -- get examples/app.dusk
cargo run --bin dawn -- run examples/app.dusk

The cache

dawn clones each repository into a content cache, and the dusk loader resolves git imports from there. The cache root is $DAWN_CACHE, or ~/.dawn/cache when that is unset. The layout mirrors the import path.

~/.dawn/cache/
  github.com/user/repo/        a shallow clone of the repository
    module.dusk                a module inside it, resolved by an import

An import github.com/user/repo/module resolves to ~/.dawn/cache/github.com/user/repo/module.dusk. Setting $DAWN_CACHE points a build at a clean cache, which is also how the toolchain’s own tests check resolution without touching a real home directory.

dawn needs git

dawn shells out to the system git, so git has to be on your path to fetch. Each repository is a shallow clone, and dawn get skips repositories already present in the cache.

Current limitations

The fetch path runs end to end, and it is minimal on purpose. As of 0.3.3:

• An import resolves against the latest clone in the cache. There is no version selection; whatever was cloned last is what builds.
• There is no lock file, so a fresh machine is not guaranteed to build the same bytes.
• dawn get fetches only the root file’s direct imports. It does not walk the imports of fetched packages.
• There is no integrity check on fetched modules.

Version pinning (a git tag or commit per package), a lock file, graph fetch, integrity hashes, and a vendor mode come in later releases. See the roadmap and the dawn reference for detail.