matlab.buildtool.tasks.CleanTask Class

Namespace: matlab.buildtool.tasks
Superclasses: matlab.buildtool.Task

Task for deleting outputs and traces

Since R2023b

Description

The matlab.buildtool.tasks.CleanTask class provides a task for deleting task outputs as well as traces of tasks that support incremental builds. When you delete the trace of a task, the build tool no longer considers the task as up to date.

You can run a CleanTask instance without an argument to delete the outputs and traces of all other tasks in the build plan, or with an argument to delete the outputs and traces of specified tasks. For more information, see Run CleanTask Instance.

Creation

Description

task = matlab.buildtool.tasks.CleanTask creates a task for deleting outputs and traces of tasks.

task = matlab.buildtool.tasks.CleanTask(Name=Value) sets the Description and Dependencies properties, which the class inherits from the Task class, using one or more name-value arguments. For example, task = matlab.buildtool.tasks.CleanTask(Description="Reset tasks") creates a task with the specified description for deleting task outputs and traces.

The CleanTask class also inherits the other properties of the Task class, but you cannot set those properties during task creation.

Examples

Delete Task Outputs

Delete the outputs and traces of tasks that support incremental builds by using the CleanTask class.

Open the example and then navigate to the clean_task_example folder, which contains a build file as well as a C source file named explore.c.

cd clean_task_example

This code shows the contents of the build file. The build file contains two built-in tasks and one task created with a local task function:

• The "clean" task deletes outputs and traces of the other tasks in the build file.

• The "mex" task compiles explore.c into a MEX file and saves the result to a folder named output in your current folder. You must have a supported C compiler installed on your system to run this task.

• The "archive" task creates an archive of its inputs.

function plan = buildfile
import matlab.buildtool.tasks.CleanTask
import matlab.buildtool.tasks.MexTask

% Create a plan from task functions
plan = buildplan(localfunctions);

% Add a task to delete outputs and traces
plan("clean") = CleanTask;

% Add a task to build a MEX file
plan("mex") = MexTask("explore.c","output");

% Specify the input and output of the "archive" task
plan("archive").Inputs = plan("mex").MexFile;
plan("archive").Outputs = "mex.zip";
end

function archiveTask(context)
% Create ZIP file
task = context.Task;
zip(task.Outputs.paths,task.Inputs.paths)
end

Run the "archive" task. Because the input of the "archive" task is the output of the "mex" task, the build tool runs the "mex" task before running the "archive" task.

buildtool archive

** Starting mex
mex explore.c -output output\explore.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex

** Starting archive
** Finished archive

Run the "archive" task again. The build tool skips both of the tasks because none of the inputs or outputs of the tasks have changed.

buildtool archive

** Skipped mex (up-to-date)

** Skipped archive (up-to-date)

Run the "clean" task to delete outputs and traces of the other tasks in the plan. When you delete the outputs or the trace of a task, the build tool no longer considers the task as up to date.

buildtool clean

** Starting clean
Deleted 'C:\work\clean_task_example\mex.zip' successfully
Deleted 'C:\work\clean_task_example\output\explore.mexw64' successfully
** Finished clean

Rerun the "archive" task. The build tool also runs the "mex" task because it is no longer up to date.

buildtool archive

** Starting mex
mex explore.c -output output\explore.mexw64 
Building with 'MinGW64 Compiler (C)'.
MEX completed successfully.
** Finished mex

** Starting archive
** Finished archive

Now, delete only the output and trace of the "archive" task.

buildtool clean("archive")

** Starting clean
Deleted 'C:\work\clean_task_example\mex.zip' successfully
** Finished clean

Run the "archive" task again to produce a fresh archive. The build tool skips the "mex" task because it is up to date.

buildtool archive

** Skipped mex (up-to-date)

** Starting archive
** Finished archive

More About

Run CleanTask Instance

You can run a CleanTask instance by using the buildtool command or the run method. If you do not specify an argument for the CleanTask instance, the task deletes the outputs and traces of all other tasks in the build plan. If you specify an argument including task names, the task deletes the outputs and traces of the specified tasks.

For example, create a CleanTask instance in your build file.

plan("clean") = matlab.buildtool.tasks.CleanTask;

Run the "clean" task to delete the outputs and traces of all other tasks in the build file.

buildtool clean

To delete the outputs and traces of certain tasks, specify the task names as a string vector. For example, delete the outputs and the trace of a task named "task1".

buildtool clean("task1")

Delete the outputs and traces of several tasks.

buildtool clean(["task1" "task2" "task3"])

If you use the run method, specify the task argument as a scalar cell containing the task names.

run(plan,"clean",{["task1" "task2" "task3"]})

For more information on how to run tasks that accept arguments, see Create Tasks That Accept Arguments.

Tips

• You cannot overwrite or remove the actions of a built-in task, but you can specify additional task actions. For example, append an action to the Actions property of a built-in task.

  plan("myTask").Actions(end+1) = @myAction;

Version History

Introduced in R2023b

R2024b: Delete additional task outputs

To delete outputs of a task, a CleanTask instance searches through both the actual and expected outputs:

• Actual outputs — Outputs on disk that the task produced when it last ran successfully (stored in the task trace)

• Expected outputs — Outputs that the task would produce if it ran at cleanup time (specified in the build plan)

For example, if you change the inputs or outputs of a task in the build file, a CleanTask instance deletes the outputs on disk from the last task run even if the build file no longer represents them. In previous releases, a CleanTask instance misses such outputs because it searches only for outputs that are expected to exist on disk when cleanup takes place.