Documentation
Getting Started
Task Lifecycle

Task Lifecycle

Terrabuild aims at scheduling tasks to complete goals (which are targets). For this, Terrabuild creates a graph with all automatically discovered projects, targets and project dependencies. For each tasks (which are nodes of this graph), Terrabuild has to decide what to do.

To decide what to do, Terrabuild relies on a cache (either local or remote). A cache is driven by a key: this key (which is the unique identifier of the task) is built using:

  • hash of files of the project
  • project dependencies
  • variables used for task
ℹ️
Note that unless you are using specific information from commit (like the terrabuild_head_commit variable), this key is unique across branches. This is a really major concept since this enables important optimization.

Once the key has been computed, Terrabuild applies following decision tree to discover what to do with this task:

flowchart TB

classDef start fill:black
classDef build stroke-width:4px,stroke:black,fill:white
classDef restore stroke-width:4px,stroke:black,fill:white
classDef decision stroke:black
classDef use-cache fill:#b0f1da,stroke:black,stroke-dasharray: 10 2,rx:10,ry:10
classDef dynamic fill:#CEB1FB,stroke:black,stroke-width:1px,stroke-dasharray: 5 2,rx:10,ry:10

start((" "))
force{{Force ?}}

restore((Restore))
build((Build))


subgraph use-cache[ ]
  cacheable{{Cached ?}}
  younger{{Out of date ?}}
  retry{{Retry ?}}

  subgraph dynamic[ ]
    external{{External state ?}}
    state-changed{{External state out of date ?}}
  end
end


start --> force

force -- yes --> build
force -- no --> cacheable

cacheable -- no --> build
cacheable -- yes --> younger

younger -- yes --> build
younger -- no --> retry

retry -- yes --> build
retry -- no --> external

external -- yes --> state-changed
external -- no --> restore

state-changed -- yes --> build
state-changed -- no --> restore

class start start
class build build
class restore restore
class force,cacheable,younger,retry,ext,state-changed decision
class use-cache use-cache
class dynamic dynamic
ConditionDescription
Forceeither --force (global) or rebuild (target)
Cachedall operations on target are cacheable and task has been previously built
Out of dateprevious build is younger than dependencies
Retryprevious build has failed
External statesome operations on target have an externally managed state
External state out of dateexternal state is considered modified

Decision is either Build or Restore leading to a new state for the task. Note that if task is built (or built again), this triggers in turn build of dependent nodes.

In all cases, new state is stored in local cache. If connected to a backend, task state is uploaded and can be used in next executions.

Last updated on
GraphInstall