Skip to content

targets.md

Latest commit

 

History

History
157 lines (109 loc) · 3.27 KB

targets.md

File metadata and controls

157 lines (109 loc) · 3.27 KB

Targets

Home > User Guide > Targets

A target is an exported function in a stavefile that Stave can invoke from the command line.

Function Signatures

Targets must have one of these signatures:

func Target()
func Target() error
func Target(ctx context.Context)
func Target(ctx context.Context) error

Targets may also accept typed arguments after the optional context. See Arguments.

Naming and Invocation

Target names are case-insensitive. A function named Build can be invoked as:

stave build
stave Build
stave BUILD

Documentation

The first sentence of a function's doc comment becomes its synopsis in stave -l:

// Build compiles the application. It produces a binary in ./bin.
func Build() error {
    // ...
}

Output of stave -l:

Targets:
  build    compiles the application.

Use stave -i build to see the full doc comment.

Multiline Support

By default, Stave collapses multiline doc comments into a single line for the stave -l output. To retain line returns, use the --multiline flag or add the //stave:multiline directive to your stavefile:

//go:build stave

//stave:multiline

package main

// Build compiles the application.
// It produces a binary in ./bin.
func Build() error {
    // ...
}

Now stave -l will preserve the line break:

Targets:
  build    compiles the application.
           It produces a binary in ./bin.

Default Target

Set a default target to run when no target is specified:

var Default = Build

Now stave with no arguments runs Build.

To ignore the default and list targets instead, set STAVEFILE_IGNOREDEFAULT=1.

Aliases

Define alternative names for targets:

var Aliases = map[string]any{
    "b": Build,
    "t": Test,
}

Now stave b runs Build and stave t runs Test.

Importing Targets

Import targets from other packages using the stave:import directive:

import (
    // stave:import
    "github.com/yourorg/shared/buildtasks"

    // stave:import deploy
    "github.com/yourorg/shared/deploytasks"
)
  • Root import: Targets are available by their original names.
  • Aliased import: Targets are prefixed with the alias (e.g., deploy:production).

The imported package must contain valid target functions.

Build Tags in Imported Packages

Imported packages can use the //go:build stave build tag, just like your main stavefile. Stave will automatically detect and include these files during the build process. This is particularly useful for shared build logic that should not be included in normal Go builds.

Exit Codes

Return an error to indicate failure:

func Build() error {
    if err := sh.Run("go", "build"); err != nil {
        return err
    }
    return nil
}

Use st.Fatal or st.Fatalf to exit with a specific code:

func Deploy() error {
    if os.Getenv("ENV") == "" {
        return st.Fatal(2, "ENV must be set")
    }
    // ...
}

See Also