urknall: github.com/dynport/urknall Index | Examples | Files | Directories

package urknall

import "github.com/dynport/urknall"

Package urknall

See http://urknall.dynport.de for detailed documentation.



Package Files

build.go cached_command.go command_runner.go constants.go logging.go package.go package_impl.go string_command.go target.go task.go template_func.go urknall.go utils.go validation.go

func DryRun Uses

func DryRun(target Target, tpl Template) (e error)

A shortcut creating and runnign a build from the given target and template with the DryRun flag set to true. This is quite helpful to actually see which commands would be exeucted in the current setting, without actually doing anything.

func OpenLogger Uses

func OpenLogger(w io.Writer) io.Closer

OpenLogger creates a logging facility for urknall using the given writer for output. Note that the resource must be closed!


logger := OpenLogger(os.Stdout)
defer logger.Close()

// short: defer OpenLogger(os.Stdout).Close()

func Run Uses

func Run(target Target, tpl Template, opts ...func(*Build)) (e error)

A shortcut creating and running a build from the given target and template.

type Build Uses

type Build struct {
    Target            // Where to run the build.
    Template          // What to actually build.
    Env      []string // Environment variables in the form `KEY=VALUE`.
    Confirm  func(actions ...*confirm.Action) error
    // contains filtered or unexported fields

A build is the glue between a target and template.


package main

import (


func main() {
    template := &ExampleTemplate{}
    target, e := NewLocalTarget()

    if e != nil {

    build := &Build{Target: target, Template: template}
    if e := build.Run(); e != nil {

// An example template function. This is helpful to render templates that don't
// need configuration like the following ExampleTemplate.
func AnExampleTemplateFunc(pkg Package) {
    pkg.AddCommands("example", Shell("echo template func"))

// A simple template with configuration.
type ExampleTemplate struct {
    Parameter string `urknall:"default=example"`
    Boolean   bool   `urknall:"required=true"`

// Templates must implement the Render function.
func (tmpl *ExampleTemplate) Render(pkg Package) {
    // Template parameters can be used in go's text/template style.
    pkg.AddCommands("base", Shell("echo {{ .Parameter }}"))
    if tmpl.Boolean { // Only add template function if Boolean value is true.
        pkg.AddTemplate("func", TemplateFunc(AnExampleTemplateFunc))

// Need to implement a command. Those come with the default code created by the
// `urknall init` method, so in most cases this must not be done manually.
type ShellCmd struct {
    cmd string

func (c *ShellCmd) Shell() string {
    return c.cmd

// Helper function to easily create a ShellCmd.
func Shell(cmd string) cmd.Command {
    return &ShellCmd{cmd: cmd}

func (*Build) DryRun Uses

func (b *Build) DryRun() error

func (*Build) Run Uses

func (b *Build) Run() error

This will render the build's template into a package and run all its tasks.

type Package Uses

type Package interface {
    AddTemplate(string, Template)       // Add another template, nested below the current one.
    AddCommands(string, ...cmd.Command) // Add a new task from the given commands.
    AddTask(string, Task)               // Add the given tasks to the package with the given name.

The package is an interface. It provides the methods used to add tasks to a package. The packages's AddTemplate and AddCommands methods will internally create tasks.

Nesting of templates provides a lot of flexibility as different configurations can be used depending on the greater context.

The first argument of all three Add methods is a string. These strings are used as identifiers for the caching mechanism. They must be unique over all tasks. For nested templates the identifiers are concatenated using ".".

type Target Uses

type Target interface {
    Command(cmd string) (target.ExecCommand, error)
    User() string
    String() string
    Reset() error

The target interface is used to describe something a package can be built on.

func NewLocalTarget Uses

func NewLocalTarget() (Target, error)

Use the local host for building.

func NewSshTarget Uses

func NewSshTarget(address string) (Target, error)

Create an SSH target. The address is an identifier of the form `[<user>@?]<host>[:port]`. It is assumed that authentication via public key will work, i.e. the remote host has the building user's public key in its authorized_keys file.

func NewSshTargetWithPassword Uses

func NewSshTargetWithPassword(address, password string) (Target, error)

Special SSH target that uses the given password for accessing the machine. This is required mostly for testing and shouldn't be used in production settings.

func NewSshTargetWithPrivateKey Uses

func NewSshTargetWithPrivateKey(address string, key []byte) (Target, error)

Create a SSH target with a private access key

type Task Uses

type Task interface {
    Add(cmds ...interface{}) Task
    Commands() ([]cmd.Command, error)

A task is a list of commands. Each task is cached internally, i.e. if an command has been executed already, none of the preceding tasks has changed and neither the command itself, then it won't be executed again. This enhances performance and removes the burden of writing idempotent commands.

func NewTask Uses

func NewTask() Task

Create a task. This is available to provide maximum flexibility, but shouldn't be required very often. The resulting task can be registered to an package using the AddTask method.

type Template Uses

type Template interface {
    Render(pkg Package)

A template is used to modularize the urknall setting. Templates are rendered into a package and during rendering tasks can be added.

type TemplateFunc Uses

type TemplateFunc func(Package)

This is a short-cut usable for templates without configuration, i.e. where no separate struct is required.

func (TemplateFunc) Render Uses

func (f TemplateFunc) Render(p Package)


cmdThe Command Interfaces
urknallThe urknall binary: see http://urknall.dynport.de/docs/binary/ for further information.
utilsUtil functions that don't fit anywhere else.

Package urknall imports 26 packages (graph) and is imported by 6 packages. Updated 2017-09-14. Refresh now. Tools for package owners.