Cache Task Outputs

R2026b

Since R2026b

The MATLAB^® build tool supports task output caching to improve build performance by reusing outputs from earlier builds. When you set up a local output cache for a project, the build tool can store task outputs and use them in subsequent builds if it determines that task inputs, actions, and arguments have not changed. Using cached outputs avoids rerunning tasks and reduces build time when saving to and loading from the cache is faster than regenerating outputs.

By default, the build tool does not cache task outputs. To enable task output caching, specify the -outputCache option with the buildtool command. When you run a build using the -outputCache option, the build tool:

• Saves task outputs to the output cache. The build tool includes outputs of tasks that run and outputs of up-to-date tasks that are skipped, provided that their outputs do not already exist in the cache.

• Skips tasks whose expected outputs are already in the output cache. The build tool uses cached outputs of a task only if it determines that the task inputs, actions, and arguments have not changed.

Task output caching is possible for tasks that:

• Support incremental builds.

• Generate outputs in the plan root folder or its subfolders.

• Have the DisableOutputCache property set to false.

The build tool stores cached task outputs in the outputCache subfolder of the .buildtool folder. During builds that use the output cache, the build tool periodically removes cached outputs that have not been used for over seven days.

Use Cached Task Outputs

This example shows how to set up an output cache and use it to retrieve task outputs for a task whose inputs have not changed. You can run the builds in this example using your own build file if it has:

• A matlab.buildtool.tasks.CleanTask instance named "clean"

• One or more default tasks that support incremental builds and generate outputs in the plan root folder or its subfolders

This code shows the contents of the build file used in this example for illustrative purposes. To demonstrate task output caching, the "test" task in the build file supports incremental builds (because its SourceFiles property is nonempty) and generates outputs in subfolders of the plan root folder. The build file assumes that the source and test code in the current folder are located in the source and tests subfolders, respectively.

function plan = buildfile
import matlab.buildtool.tasks.*

plan = buildplan(localfunctions);

addpath("source")

plan("clean") = CleanTask;
plan("check") = CodeIssuesTask(Results="code-issues/results.sarif");
plan("test") = TestTask("tests", ...
    SourceFiles="source", ...
    TestResults="test-results/results.xml", ...
    CodeCoverageResults="code-coverage/results.xml");

plan.DefaultTasks = ["check" "test"];
end

Using the -outputCache option, run the default tasks in the plan returned by the build file. The "check" and "test" tasks run and save their outputs to subfolders of the plan root folder. Additionally, the build tool sets up a local output cache and stores the outputs of the "test" task in the cache. Because matlab.buildtool.tasks.CodeIssuesTask instances do not support incremental builds, the output cache does not contain the output of the "check" task.

buildtool -outputCache

** Starting check

Analysis Summary:
    Total Files: 3
         Errors: 0 (Threshold: 0)
       Warnings: 0 (Threshold: Inf)
           Info: 0 (Threshold: Inf)
Results:
    SARIF: C:\work\code-issues\results.sarif
** Finished check

** Starting test
...
Cobertura XML code coverage report has been saved to:
 C:\work\code-coverage\results.xml

Test Summary:
    Total Tests: 3
         Passed: 3
         Failed: 0
     Incomplete: 0
       Duration: 0.23579 seconds testing time.
                 
Test Results:
    JUnit: C:\work\test-results\results.xml
Code Coverage:
    Cobertura: C:\work\code-coverage\results.xml
** Finished test

Build Successful:
    2 Tasks: 0 Failed, 0 Skipped
    10.265 sec total build time

Delete all the task outputs. The "clean" task deletes outputs and traces of the other tasks in the plan, but it does not operate on cached outputs.

buildtool clean

** Starting clean
Deleted 'C:\work\code-coverage\results.xml'
Deleted 'C:\work\code-issues\results.sarif'
Deleted 'C:\work\test-results\results.xml'
** Finished clean

Build Successful:
    1 Task: 0 Failed, 0 Skipped
    0.54015 sec total build time

Run a new build using the output cache. The build tool does not run the "test" task to regenerate its deleted outputs. Instead, it skips the task and loads the cached outputs. If you do not specify the -outputCache option, the build tool runs the task without referencing the output cache.

buildtool -outputCache

** Starting check

Analysis Summary:
    Total Files: 3
         Errors: 0 (Threshold: 0)
       Warnings: 0 (Threshold: Inf)
           Info: 0 (Threshold: Inf)
Results:
    SARIF: C:\work\code-issues\results.sarif
** Finished check

** Skipped test (from cache)

Build Successful:
    2 Tasks: 0 Failed, 1 Skipped
    2.4433 sec total build time

Run another build. The build tool again skips the "test" task because the task is up to date.

buildtool -outputCache

** Starting check

Analysis Summary:
    Total Files: 3
         Errors: 0 (Threshold: 0)
       Warnings: 0 (Threshold: Inf)
           Info: 0 (Threshold: Inf)
Results:
    SARIF: C:\work\code-issues\results.sarif
** Finished check

** Skipped test (up-to-date)

Build Successful:
    2 Tasks: 0 Failed, 1 Skipped
    1.7347 sec total build time