Documentation
Workspace
Target Block

Target Block

The target block describes global requirements for running a target across all projects in the workspace. A target has a unique name in the scope of the WORKSPACE file (see identifier). These global target definitions can be overridden or extended in individual PROJECT files.

Dependency Syntax

Terrabuild uses special syntax to express target dependencies:

  • target.^<target> - Ancestor dependency syntax. The ^ symbol means “ancestor” or “upstream”. This ensures that the specified target is completed for all dependency projects before the current target runs.

  • target.<target> - Current project dependency. This ensures the specified target is completed for the current project before proceeding.

Understanding target.^build

When you write depends_on = [ target.^build ], you’re saying: “Before building this target, ensure the build target is completed for all projects that this project depends on.”

Example Scenario:

  • Project A depends on Projects B and C
  • Project B depends on Project D

When building Project A’s build target with depends_on = [ target.^build ]:

  1. Terrabuild identifies that Project A depends on B and C
  2. Terrabuild ensures Project B’s build completes (which may require Project D’s build first)
  3. Terrabuild ensures Project C’s build completes
  4. Only then does Terrabuild build Project A

This creates a cascading dependency resolution that ensures all upstream dependencies are built in the correct order.

See Key Concepts for more details on dependency resolution.

Example below for project A with dependencies on projects B and C.

flowchart LR
  classDef default fill:moccasin,stroke:black
  classDef project fill:gainsboro,stroke:black,rx:10,ry:10
  classDef build fill:palegreen,stroke:black,rx:20,ry:20
  classDef publish fill:skyblue,stroke:black,rx:20,ry:20
  classDef target fill:white,stroke-width:2px,stroke-dasharray: 5 2

  subgraph A["Project A"]
    subgraph targetBuildA["target build"]
      direction LR
    end

    subgraph targetPublishA["target publish"]
      direction LR
    end

    class targetBuildA build
    class targetPublishA build
  end

  subgraph B["Project B"]
    subgraph targetBuildB["target build"]
      direction LR
    end

    class targetBuildB build
  end

  subgraph C["Project C"]
    subgraph targetBuildC["target build"]
      direction LR
    end

    class targetBuildC build
  end

  targetBuildA -- ^build --> targetBuildB
  targetBuildA -- ^build --> targetBuildC
  targetPublishA -- build --> targetBuildA
  
  class A,B,C project

Example Usage 

target build {
    depends_on = [ target.^build
                   target.init ]
    build = ~cascade
    artifacts = ~managed
}

Argument Reference

The following arguments are supported:

  • identifier - (Mandatory) Identifier of the target. This defines the target name that applies globally to all projects.

  • depends_on - (Optional) List of required targets this target depends on.

    Ancestor Dependencies (target.^<target>): Forces completion of the specified target for all dependency projects. For example, target.^build means “ensure build target completes for all projects this project depends on”. This is the most common pattern for ensuring dependencies are built first.

    Current Project Dependencies (target.<target>): Forces completion of the specified target for the current project only. For example, target.build means “ensure build target completes for this project before proceeding”.

    You can mix both types: depends_on = [ target.^build, target.test ] means “build all dependencies first, then run this project’s test target, then proceed”.

    Default is no dependencies. See Key Concepts for detailed examples.

  • build - (Optional) Override default build mode. By default, the target is built if the hash has changed (~auto). Possible values:

    • ~auto - Build when changes are detected (default)
    • ~always - Always build, ignoring cache
    • ~cascade - Build if parent must build

  • artifacts - (Optional) Override cacheability of the artifacts. By default, the value is the cacheability of the last command. Possible values:

    • ~none - Do not cache artifacts
    • ~workspace - Cache artifacts in workspace cache
    • ~managed - Cache artifacts in managed cache (Insights)
    • ~external - Cache artifacts externally
graph BT
start -- build --> A["Project A"] -- build --> B["Project B"]
                   A["Project A"] -- build --> C["Project C"]
Last updated on
Extension Block