Documentation
Syntax

Syntax

There are two different configuration types:

  • WORKSPACE
  • PROJECT

Both share the same syntax - but not the same functionalities - and are based on a simplified HCL syntax:

  • comments are a single line and start with a #
  • blocks
  • attributes
  • order is not important but for commands in target

WORKSPACE

WORKSPACE is a mandatory file at the root of your repository. It describes targets dependencies, configurations and default extensions configuration.

WORKSPACE
# before building, we want all dependencies to be completed
target build {
  depends_on = [ target.^build ]
}

# docs has no configuration (hence no dependencies)
target docs { }

# to publish, we need both build and docs to be completed
# also this target is always rebuilt regardless of caching status
target publish {
  rebuild = true
  depends_on = [ target.build target.docs ]
}

# configuration used by default
variable config {
  description = "configuration to build"
  default = "Debug"
}

# configure the internal extension @dotnet
# it uses a build container and provides default parameters for all actions of @dotnet
extension @dotnet {
  container = "mcr.microsoft.com/dotnet/sdk:8.0"
  defaults {
    configuration = var.config
  }
}

# @npm extension uses only a build container
extension @npm {
  container = "node:20"
}

# @docker extension is built without a container (hence must be deployed on host)
# also default parameters are provided for all actions of @docker 
extension @docker {
  defaults {
    arguments = { configuration: var.config }
    image = "ghcr.io/example/${terrabuild.project}"
  }
}

PROJECT

PROJECT is a mandatory file for each project. It defines how the project shall be built. It also describes outputs.

PROJECT

# provide the configuration for project - note
project {
    # a list of files/directory to ignore (globbing format)
    ignores = [ "**/*.binlog" ]
  
    # this project has a dependency on `../other-project` - see `ancestor` build target
    dependencies = [ "../other-project" ]
  
    # outputs to cache
    outputs = [ "bin/" "obj/" "**/*.binlog" ]
}

# this is the implementation of the build target
# it provides a list of action to run in order to complete the target
target build {
    # invoke the publish command - also pass log parameter
    @dotnet publish { log = true }

    # invoke docker build command - parameter are optional
    @docker build { }
}

# another target implementation
target publish {
    @docker push { }
}

Some extensions provide an init capability to discover and configure automatically the project defaults.

PROJECT
# @dotnet extension is able to find project to build, ignores, outputs, and all dependencies
project {
    # define labels for scoping the build
    labels = [ "app" "dotnet" ]
    @dotnet { }
}

target build {
    @dotnet publish { log = true }
    @docker build { }
}

target publish {
    @docker push { }
}
scaffolding workspace project extensibility
Last updated on
Getting Started