saker.build Documentation TaskDoc JavaDoc

Task development

Tasks are the basic units of execution in the build system. We recommend you read the following material beforehand:

Basics

The first step of building your own task is to find a repository that can provide access to it. As the Nest repository is the default repository of tasks for the build system, we recommend using that. The following examples are going to use the Nest repository, but if you don't want to use that, you can freely adapt the examples on your own discretion. See Repository development for developing repositories. We recommend using the saker.nest repository to develop and publish tasks for the build system.

Each task in the build system implements the Task interface. They contain a single function run(TaskContext) that allows them to execute their operations for the given build execution. These task objects are stateful objects, every time a task is invoked, a new Task instance is created by the build system. The Task objects are created by their defining TaskFactory implementations. From now on, we're going to referer to the TaskFactory - Task pairs as task in general.

Task factories

Task factories are stateless objects that specify how a task should be executed. Their responsibility to exactly specify how a task is invoked and create their Task instances when necessary. A TaskFactory is an immutable object, which can be compared by equality to other TaskFactory objects.
When two TaskFactory objects equal, it means that given the same build environment, they will use exactly the same inputs and produce semantically the same outputs. This equality is an important aspect of task factories, as the build system can detect changes based on these equality checks.

Task factories also specify different aspects of their task executions, and that is discussed later. (See Task capabilities.)

Task factories are also strongly recommended to implement some serialization mechanism, preferrably implementing the Externalizable interface.

Task identifiers

Task identifiers are immutable objects that uniquely identify a given task in the build system. They are a subclass of TaskIdentifier, and are required to implement the equals(Object) and hashCode() contract of the Java Object functions.

During an execution of a task, it can choose to start new tasks. Each task is identified by the supplied task identifier along with the task factory. During a single build execution only a single task can be run for a single task identifier.

Task identifiers are also used to look up the previous execution results to a task when it is run again. When a task with task identifier of taskid is run, and finishes successfully, then the next time it is run, the previous outputs of the task taskid will be provided to it in order to properly implement incremental functionality.