Bobfile

project

type: string

Name of the project used for artifact inspection or artifact uploads generated from current bob file. If the value is not set, the working directory of the bobfile will be used.

The value can be either a custom string or an URL of the remote store where artifacts are uploaded.

project: bob.build/benchkram/bob

import

type: array

The import keyword can be used to import tasks defined in another bob.yaml file. All tasks from the imported Bobfile are added to the current build map.

In the below example a ./backend/bob.yaml and ./ui/bob.yaml can be imported like this:

## bob.yaml
import:
  - backend
  - ui

Each imported tasks can be referenced by prepending the import path of it's Bobfile. E.g. a task with the name build defined in .backend/bob.yaml can be referenced as backend/build.

Imports work recursively. This means that 3rd- and 4th- till Xth- level tasks are added.

build type:map

A map holding individual build tasks. Each map key is taken as a task name.

build:task

A build task can be seen as the instructions to build a target or to execute a certain cmd without generating targets. Though the more common case for a task is to generate some kind of target. By default the "cmd" part of a task is only executed if any of the input changed or a target can't be loaded from the cache.

## bob.yaml
dependencies: [ go_1_19 ]
build:
  build:
    input: main.go
    cmd: go build -o run
    target: run
    dependsOn:
      - fmt
  fmt:
    cmd: go fmt ./...

input

type: array, text

Inputs and the task description itself determine when a task is rebuild. It's usually ok to start with a * and optimise later. Just be aware that each input file is considere during input-hash generation. This can be an expensive operation on large repositories when many files are involved.

Some examples:

input: main.go

Block style

input: |-
  main.go

Use ! to ignore files

input: |-
  *
  !.gitignore

If you want to go fancy use globbing, double star (**) syntax is supported.

input: |-
  // match files ending in ".md" in subdirectorys of "dir"
  dir/*/*.md

  // match everything that contains a dot in "dir"
  dir/**/*.*

  // ignore all ".gitignore" files in "dir"
  !dir/**/.gitignore

Ignore will overrule any matched input.

cmd

type: array, text

The cmd keyword is used to declare the commands to be execute. Block style is supported. Under the hood an internal shell is used, so you can use the full power of "sh"

Example:

## bob.yaml
build:
  hello:
    cmd: echo "Hello World"
  hello-blockstyle:
    cmd: |-
      echo Hello
      echo World
  hello-to-file:
    cmd: |-
      echo "Hello World" > hello
  multiline:
    cmd: |-
      echo "Hello \
      World"
  script:
    cmd: ./script.sh

target

type: array, text

A target can be a file, directory or even a docker image. Each file or image created in the "cmd" part should be listed as a target. Targets are archived in a artifact store on your local machine ~/.bobcache/artifacts indexed by the hash of the build inputs and the build description. As long as the input hash doesn't change targets are loaded from the local cache.

Hint: docker images require a local docker registry.

Examples:

Adding a file as target

## bob.yaml
dependencies: [ go_1_19 ]
build:
  build:
    input: main.go
    cmd: go build -o run
    target: run

Mutiline path targets

    ...
    target: |-
      file
      dir/

Another way to define mutiline path targets

    ...
    target:
      path: |-
        file
        dir/

Docker image target

    ...
    target:
      image: postgres:latest

Multiline docker image targets

    ...
    target:
      image: |-
        postgres:latest
        minio:latest

To have a target image you need to specify the full name:tag format.

dependsOn

type: array

The dependsOn keyword let's you define tasks which have to finish execution before the actual task can start doing it's work.

## bob.yaml
build:
  build:
    input: main.go
    cmd: go build -o run
    target: run
    dependsOn:
      - taskone
      - tasktwo
  taskone: ...
  tasktwo: ...

You can also depend on build tasks added through the import keyword . Those tasks are prefixed with the relative path to their bob.aml. To depend on a task named build defined in dirone/ use..

build:
  build:
    ...
    dependsOn:
      - dirone/build

rebuild

type: enum

With the rebuild keyword the default rebuild behaviour can be altered. By default it is set to on-change. It also acceptsalways which tells the task not to take input changes into account, instead it will always execute the task.

dependencies

type: array

Task level dependencies take precedence over dependencies defined in the Bobfile.

run type:map

A map holding individual run tasks. Each map key is taken as a run name.

Note: Run tasks are still experimental.

run:task

The run keyword is used to describe how binary or compose files can be run. It is possible to depend on other run tasks as well as on build tasks. A run assures all dependecies are started or build before doing it's work

Note: Run tasks are still experimental.

type

binary | compose

path

Path to a binary or compose file Defaults to: docker-compose.yaml for run:type: compose

dependsOn

Example:

## bob.yaml
build:
  build: ...
run:
  binary:
    type: binary
    path: ./run
    dependson:
      - build
      - database
  database:
    type: compose

dependencies

type: array

The dependencies keyword allows you to add dependencies valid for all tasks in a Bobfile. These dependencies will be downloaded or built with Nix.

Dependencies defined on a build task will take precedence over the ones defined at the Bobfile level. The values from this keyword can be either the package name or a path relative to the bobfile of a .nix file.

Example:

## bob.yaml
build:
  run-go-version:
    cmd: go version
    dependencies:
        - go_1_18
dependencies:
  - ginkgo.nix
  - php74

nixpkgs

type: string

The URL of Nixpkgs to be used when installing dependencies. If no value is specified, the local <nixpkgs> channel is used for your system.

## bob.yaml
nixpkgs: https://github.com/NixOS/nixpkgs/archive/6eed87d4490ce045dda1091999d1e38605afb8ea.tar.gz

Picking the commit can be done via status.nixos.org, which lists all the releases and the latest commit that has passed all tests in the Commit column.

When choosing a commit, it is recommended to follow either:

• the latest stable NixOS release by using a specific version, such as nixos-22.05
• the latest unstable release via nixos-unstable.

Alternatively, you can go to Nixpkgs repository, pick a commit id and add it:

nixpkgs: https://github.com/NixOS/nixpkgs/archive/{commitID}.tar.gz