Create Custom Reusable Tasks

Since R2025a

To simplify build definition, you can create custom task classes and reuse them across different build files. For instance, you can create a custom task class to represent a specific task and then include that task in various build files by instantiating the task class in each build file. To implement a custom task class, derive your class from the matlab.buildtool.Task class and use framework-specific attributes to specify the task action, inputs, and outputs. Consider creating a custom task class if the built-in task classes in the matlab.buildtool.tasks namespace do not address your needs.

This example shows how to implement a task class for generating a ZIP archive of files and folders. In this example, you create a task class using the TaskAction, TaskInput, and TaskOutput attributes to specify the task action, input, and output. Then, you instantiate the task class in a build file and run the resulting task.

Create Task Class

You can implement a custom task class by subclassing the matlab.buildtool.Task class and then adding the required properties and methods to the subclass.

For example, in a file named ArchiveTask.m in your current folder, create the ArchiveTask task class for generating a ZIP archive of files and folders. (For the complete code of the task class used in this example, see Task Class Definition.)

classdef ArchiveTask < matlab.buildtool.Task
    
end

Specify Task Inputs and Outputs

To represent task inputs and outputs in the task class definition, use the TaskInput and TaskOutput property attributes:

  • Task inputs — Specify properties to represent the task inputs in a properties block with the TaskInput attribute. Properties with the TaskInput attribute can be of any type.

  • Task outputs — Specify properties to represent the task outputs in a properties block with the TaskOutput attribute. Properties with the TaskOutput attribute must be of type matlab.buildtool.io.FileCollection or one of its subclasses.

Because an ArchiveTask instance operates on collections of files and folders as an input and generates a ZIP file as an output, add two properties to the task class:

  • In a properties block with the TaskInput attribute, add the Files property to define the task input. Because the task can accept collections of files and folders as its input, specify the Files property as a matlab.buildtool.io.FileCollection vector.

  • In a properties block with the TaskOutput attribute, add the Archive property to define the task output. Because the task generates a ZIP file as its output, specify the Archive property as a matlab.buildtool.io.File object.

    properties (TaskInput)
        Files (1,:) matlab.buildtool.io.FileCollection
    end

    properties (TaskOutput)
        Archive matlab.buildtool.io.File {mustBeScalarOrEmpty}
    end

For more information about the TaskInput and TaskOutput attributes, see Task Property Attributes.

Add Task Constructor

To implement the code to run when the task class is instantiated, add a task constructor to your class. For instance, the constructor can set the properties specified in the task class definition or the properties inherited from a superclass.

Add the ArchiveTask constructor to a methods block. The constructor takes two inputs to set the Files and Archive properties. The constructor also sets the Description property, which the task class inherits from the matlab.buildtool.Task class.

    methods
        function task = ArchiveTask(files,archive)
            task.Files = files;
            task.Archive = archive;
            task.Description = "Create ZIP file";
        end
    end

Specify Task Action

To specify the task action, add a single method to a methods block with the TaskAction attribute. The method must accept the task as its first input. It must also accept a matlab.buildtool.TaskContext object as its second input, which provides context-specific information to the task action.

In a methods block with the TaskAction attribute, add the createArchive method. The method calls the zip function to compress the task input (Files property) and save the resulting ZIP file as the task output (Archive property).

    methods (TaskAction)
        function createArchive(task,~)
            zip(task.Archive.Path,task.Files.paths)
        end
    end

For more information about the TaskAction attribute, see Task Method Attributes.

Task Class Definition

This code provides the complete contents of the ArchiveTask class.

classdef ArchiveTask < matlab.buildtool.Task
    properties (TaskInput)
        Files (1,:) matlab.buildtool.io.FileCollection
    end

    properties (TaskOutput)
        Archive matlab.buildtool.io.File {mustBeScalarOrEmpty}
    end

    methods
        function task = ArchiveTask(files,archive)
            task.Files = files;
            task.Archive = archive;
            task.Description = "Create ZIP file";
        end
    end

    methods (TaskAction)
        function createArchive(task,~)
            zip(task.Archive.Path,task.Files.paths)
        end
    end
end

Create Task from Task Class

Once your task class definition is complete, you can create tasks from the task class by instantiating it in your build files.

For example, in a build file named buildfile.m in your current folder, create a plan with two tasks:

  • Create the "clean" task from the matlab.buildtool.tasks.CleanTask class. A CleanTask instance deletes outputs and traces of the other tasks in the build file.

  • Create the "archive" task from the ArchiveTask class. In the build file in this example, the ArchiveTask constructor takes the collection of .m files in the current folder and its subfolders as the task input and a filename of source.zip for the task output.

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

% Create a plan with no tasks
plan = buildplan;

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

% Add a task to create a ZIP file
plan("archive") = ArchiveTask("**/*.m","source.zip");
end

Run the Task

You can run the tasks in the build file using the buildtool command.

List the tasks in the build file.

buildtool -tasks
archive - Create ZIP file
clean   - Delete task outputs and traces

Run the "archive" task. The task generates an archive named source.zip in your current folder.

buildtool archive
** Starting archive
** Finished archive

Run the task again. The build tool skips the task because neither its input nor output has changed.

buildtool archive
** Skipped archive (up-to-date)

Run the "clean" task to delete the output and trace of the "archive" task. 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\source.zip' successfully
** Finished clean

Rerun the "archive" task to generate a fresh archive.

buildtool archive
** Starting archive
** Finished archive

You can also run the tasks in your build file interactively from the MATLAB® Toolstrip. For more information, see Run Build from Toolstrip.

See Also

Functions

Classes

Topics