Incremental Tasks

Incremental tasks are used in order to improve build performance by skipping jobs which output files are created or updated after the last modification of the corresponding input files.

Tasks with one-to-one correspondence between input and output files are called partial incremental and they normally use the build pattern described in Partial Incremental Tasks. A typical example is conversion of files from one format into another.

Other incremental tasks do not have one-to-one input-output correspondence but they still have input files to be converted into one or more output files. For example input is a set of .cs files and the output is an assembly file (.dll or .exe) built from input.

Here is an incremental task template:

    task Name -Inputs ... -Outputs ... [-Jobs] {
        ...
    }

It normally defines at least these three pieces: the inputs and outputs expressions and the script that produces the output files from the input.

Inputs and outputs are often not really short expressions or even one-liners. If this is the case then use an intermediate hashtable which defines task parameters and the parameter splatting technique on the task definition:

    $param = @{
        Inputs = {
            ...
        }
        Outputs = {
            ...
        }
    }

    task Name @param {
        ...
    }

---

The inputs

It is a list of input file items or paths or a script block which gets them. For example, for all .cs files in the build directory it can be:

    task ... -Inputs (Get-Item *.cs) -Outputs ...

or almost the same with a script block:

    task ... -Inputs {Get-Item *.cs} -Outputs ...

The main difference between the first and the second is that the first input is evaluated on task creation (always) and the second only on task invocation. If a task is not always invoked then the second form may improve performance. But the first form catches potential issues earlier, before any task is invoked.

A fixed list of known absolute or relative file paths will do as well:

    task ... -Inputs Class.cs, AssemblyInfo.cs -Outputs ...

The inputs are finally resolved by the engine into the full paths represented by the automatic variable $Inputs. All input files must exist, otherwise the task fails.

---

The outputs

It is a list of output file paths or a script block which gets them. A single file path is allowed, too. Empty output is not allowed.

If any of output items is missing then the task scripts are invoked. Otherwise the engine compares timestamps. If the minimum of outputs is less than the maximum of inputs then the task scripts are invoked.

    task ... -Inputs ... -Outputs Library.dll

---

The script

The script builds the output files from the input files. There are two helper automatic variables defined: the $Inputs (array of resolved full input paths) and the $Outputs (exactly as it was defined or returned by a script block). Scripts can but do not have to use them, like in this example:

    {
        exec { csc /optimize /target:library /out:Library.dll *.cs }
    }

---

Full example

Here is the build script with an incremental task combined from the pieces above:

    # Use the .NET 4.0 compiler
    use 4.0 csc

    # Build the Library.dll if it is missing or out-of-date
    task Build -Inputs { Get-Item *.cs } -Outputs Library.dll {
        exec { csc /optimize /target:library /out:Library.dll *.cs }
    }

---

More examples

The build scripts of Mdbc and SplitPipeline. The task Meta generates the module manifest and assembly info only when Release-Notes.md changes. Normally it means that a new version is added. It is extracted from the file and used for updated module and assembly files.

The build script of PowerShellFar. The task BuildPowerShellFarHelp makes a PowerShell help file (XML) only when it is out-of-date with respect to its specified inputs.

---