hammerkit

Extending

A task can be used as a base template and extended. This is intended to reduce duplicate task definitions.

Extending tasks avoids a lot of duplicated task definitions in bigger projects and monorepos. With the extend property, a task uses another task's configuration as a template.

The following sections and examples use the two tasks in a build.tsc.yaml file, shown below. The catalog has a maintained tsc entry that you can include instead of copying.

build.tsc.yaml
tasks:
  install:
    src:
      - package.json
      - package-lock.json
    generates:
      - node_modules
    cmds:
      - npm ci
      
  build:
    deps: [ install ]
    src:
      - tsconfig.json
      - src
    cmds:
      - node_modules/.bin/tsc
    generates:
      - dist

Extend a task

Extending tsc:build uses all of its properties as a base. If nothing else is defined, the result is an exact copy that runs in the working directory of the current build file.

.hammerkit.yaml
tasks:
  build:
    extend: tsc:build
    
includes:
  tsc: ./build.tsc.yaml

Override properties in an extend

An extending task can override any property, whether the base defines it or not. Single values such as image, shell, cache and timeout are replaced by the extending task's own value. Lists and maps are added to the base's instead:

PropertyWith extend
image, shell, cache, timeoutThe task's own value replaces the base's.
cmds, src, generates, mountsThe base's entries come first, the task's own follow.
deps, needsBoth are used.
envs, labelsMerged. The task's own value wins for a name both define.

The envs of the base also include the top-level envs of the build file it comes from, so a base that reads $NODE_VERSION keeps its default when you extend it.

.hammerkit.yaml
tasks:
  build:
    extend: tsc:build
    src:
      - ../../tsconfig.base.json
    
includes:
  tsc: ./build.tsc.yaml

Here build runs the base's commands against the base's sources plus ../../tsconfig.base.json.

Container properties without an image

A task that extends a container task takes the base's image, so it may set mounts, volumeSize and capAdd without an image of its own:

.hammerkit.yaml
tasks:
  build:
    extend: base:node
    mounts:
      - .git
    cmds:
      - git log

includes:
  base: ./build.base.yaml

When neither the task nor its base has an image, they are an error: task build sets mounts, but neither it nor its base has an image.

A base's volumeSize, capAdd, resources and secrets are not passed on; set them on the extending task when it needs them.

Reset inherited values

To take nothing from the base for a property, name it in reset. The task's own value for that property still applies. In this example the dependencies are cleared, so the task runs without depending on install:

.hammerkit.yaml
tasks:
  build:
    extend: tsc:build
    reset: [deps]
    
includes:
  tsc: ./build.tsc.yaml

reset accepts deps, needs, src, generates, cmds, mounts, envs and labels. It is an error without extend. An empty deps: [] does not clear the base's dependencies, because the lists are added together.

Naming the base task

extend uses the same <prefix>:<task> addressing as dependencies: the part before the colon is the include (or reference) prefix, and the part after it is the task name in that file. extend: tsc:build means "the build task from the file included as tsc". To extend a task in the same file, use its bare name (extend: build-base).

On this page