plot

R2026b

Class: matlab.buildtool.Plan
Namespace: matlab.buildtool

Plot tasks in plan

Since R2022b

Syntax

plot(plan)

plot(plan,ShowAllTasks=tf)

Description

plot(plan) plots the tasks in the plan as a dependency graph where nodes represent tasks and edges represent dependencies. Edges in the graph flow from dependent tasks to depended-on tasks.

plot(plan,ShowAllTasks=tf) specifies whether to show the tasks in task groups. If tf is true, then the method includes the contents of task groups in the task graph. For more information about task groups, see Create Groups of Tasks. (since R2024b)

Input Arguments

plan — Plan

matlab.buildtool.Plan object

Plan, specified as a matlab.buildtool.Plan object.

tf — Option to show tasks in task groups

false or 0 (default) | true or 1

Since R2024b

Option to show the tasks in task groups, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, then the method plots the tasks in task groups. By default, the method represents a task group as a single node in the task graph.

Examples

Plot Tasks as Dependency Graph

Plot the tasks in a build plan as a dependency graph.

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

cd plot_plan_example

This code shows the contents of the build file:

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

• The "mex" task group contains two tasks named "mex:explore" and "mex:yprime". Each of these tasks compiles a source file 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 the "mex" task group.

• 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 group to build MEX files
plan("mex:explore") = MexTask("explore.c","output");
plan("mex:yprime") = MexTask("yprime.c","output");

plan("mex").Description = "Build MEX files";

% Specify the inputs and outputs of the "archive" task
plan("archive").Inputs = [plan("mex").Tasks.MexFile];
plan("archive").Outputs = "mex.zip";
end

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

Load a plan from the build file.

plan = buildfile

plan = 
  Plan with tasks:

    archive - Create ZIP file
    clean   - Delete task outputs and traces
    mex     - Build MEX files

  Show all tasks

Plot the tasks in the plan as a dependency graph. The graph displays the "clean" task, "mex" task group, and "archive" task as nodes. However, it does not include the tasks in the "mex" task group. Because the inputs of the "archive" task are the outputs of the "mex" task group, the graph also includes an edge to represent this dependency.

plot(plan)

Plot all the tasks in the plan, including the "mex:explore" and "mex:yprime" tasks in the "mex" task group.

plot(plan,ShowAllTasks=true)

Version History

Introduced in R2022b

R2026b: Improved performance when plotting tasks

Plotting tasks in a build file shows improved performance due to faster task dependency analysis by the build tool. In general, the improvement becomes more noticeable as the number of tasks and dependencies in the build file increases. The greatest improvements occur in build files with dependent task groups that contain a large number of tasks.

For example, suppose you have a build file with two task groups named "g1" and "g2", each containing 100 tasks, where the "g2" task group depends on the "g1" task group. Plotting the tasks in the build file is about 4.8x faster than in the previous release.

function plan = buildfile
import matlab.buildtool.Task

plan = buildplan;

plan("g1:t"+(1:100)) = Task;

plan("g2:t"+(1:100)) = Task;
plan("g2").Dependencies = "g1";
end

The approximate execution times are:

R2026a: 2.9 s

R2026b: 0.6 s

Plotting the tasks was timed on a Windows^® 11, Intel^® Xeon^® 6-Core Processor @ 3.60 GHz test system using the timeit function.

timeit(@() plot(buildfile))

R2026b: Visually identify cyclic task dependencies

You can visually identify cyclic task dependencies by using the plot method. After plotting your tasks as a dependency graph, verify that the graph is acyclic. If the graph contains cycles, update your build plan to remove the cyclic dependencies.

In previous releases, the method throws an error and does not create a task graph if the build plan contains cyclic dependencies.

R2024b: Show tasks in task groups

To show the tasks in task groups, specify the tf argument as true.