runprocess

Generate and run pipeline of tasks by using build system

Syntax

[buildResult,exitCode] = runprocess()

[buildResult,exitCode] = runprocess(Name=Value)

runprocess(Clean=true)

runprocess(Clean=true,DeleteOutputs=true)

runprocess(MarkStale=true)

runprocess(___,Name=Value)

Description

Run Process

[buildResult,exitCode] = runprocess() generate a pipeline of tasks and run the pipeline using the build system. The process model, processmodel.p or processmodel.m, defines the tasks in the pipeline.

[buildResult,exitCode] = runprocess(Name=Value) specifies how the pipeline of tasks runs using one or more Name=Value arguments.

Manage Task Results and Outputs

runprocess(Clean=true) cleans all task results.

runprocess(Clean=true,DeleteOutputs=true) cleans all task results and deletes task outputs.

The function only deletes the task outputs specified by the OutputPaths property of padv.TaskResult objects. The OutputDirectory of a task might still contain files.

runprocess(MarkStale=true) marks all task results as outdated.

runprocess(___,Name=Value) performs the operation for only the task iterations that meet the scope specified by one or more name-value arguments. This syntax supports only the name-value arguments that control the Scope of the operation.

Examples

Run Pipeline of Model-Based Design Tasks

Open a project and use runprocess to generate and run the pipeline using the build system.

Open the Process Advisor example project, which contains an example process model. The process model defines model-based design tasks for the pipeline.

processAdvisorExampleStart

Generate and run the pipeline and store the results in the variable results.

results = runprocess()

Run Specific Tasks

Open a project and use runprocess. To only run a specific set of tasks, provide the task names to the Tasks argument.

Open the Process Advisor example project, which contains an example process model. The process model defines the tasks for the pipeline.

processAdvisorExampleStart

Run only the tasks Generate Simulink Web View (padv.builtin.task.GenerateSimulinkWebView) and Check Modeling Standards (padv.builtin.task.RunModelStandards) by specifying the Tasks argument.

% run the Generate Simulink Web View task
% and the Check Modeling Standards tasks
runprocess(...
Tasks = ["padv.builtin.task.GenerateSimulinkWebView",...
"padv.builtin.task.RunModelStandards"])

Run Tasks Associated with Specific Artifact

Open a project and use runprocess. To only run the tasks associated with a specific artifact, provide a full path, relative path, or a padv.Artifact object to the FilterArtifact argument.

Open the Process Advisor example project, which contains an example process model. The process model defines the tasks for the pipeline.

processAdvisorExampleStart

Run tasks for the AHRS_Voter model by specifying the relative path to the model.

% run only the AHRS_Voter tasks
runprocess(...
FilterArtifact = fullfile(...
"02_Models","AHRS_Voter","specification","AHRS_Voter.slx"))

Run Specific Task Iteration, Clean Task Results, and Delete Task Outputs

Open a project and run one specific task iteration in the pipeline.

Open the Process Advisor example project, which contains an example process model.

processAdvisorExampleStart

Get a list of the task iterations in the MBD pipeline.

tasks = generateProcessTasks;

Force runprocess to run one of the task iterations by specifying Force as true and Tasks as one of the tasks in tasks.

runprocess(Force=true,Tasks=tasks(1))

When Force is true, runprocess runs the pipeline, even if the pipeline already had results that were marked as up to date.

Clean task results and delete task outputs.

runprocess(Clean=true,DeleteOutputs=true)

When you clean task results and delete task outputs, it is as if the tasks were not run.

Run Specific Process

Inside your process model, you can define multiple processes for the different build and verification workflows, environments, and other situations that your team needs a defined process for. By default, the runprocess function runs the default process. To run a different process, you can specify the Process argument.

Open the Process Advisor example project.

processAdvisorExampleStart

The model AHRS_Voter opens with the Process Advisor pane to the left of the Simulink^® canvas.

In the Process Advisor pane, click the Edit process model button to open the processmodel.m file for the project.

Replace the contents of the processmodel.m file with this code:

function processmodel(pm)
    arguments
        pm padv.ProcessModel
    end

    % Add Processes
    processA = pm.addProcess("A");
    processB = pm.addProcess("B");

    % Add Tasks
    processA.addTask(padv.builtin.task.RunModelStandards);
    processB.addTask(padv.builtin.task.CollectMetrics);
    
end

This process model code defines two processes that each contain a task. In Process Advisor, you can refresh the tasks and see the processes in the toolstrip.

Run the process named "B" by using the Process argument.

runprocess(Process = "B")

For more information on processes, see Manage Multiple Build and Verification Workflows Using Processes.

Dry Run Process with License Checkouts

Before you try to run your process in CI, you can dry run your process to validate your task inputs, generate representative task outputs, and make sure that you have the required licenses available on your CI agent.

Open the Process Advisor example project, which contains an example process model.

processAdvisorExampleStart

Perform a dry run of the process and automatically check out the licenses associated with the tasks by using the DryRun and DryRunLicenseCheckout arguments.

runprocess(DryRun = true, DryRunLicenseCheckout = true)

For more information, see Dry Run Tasks to Test Process Model.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: runprocess(Force=true)

Example: runprocess(Clean=true,DeleteOutputs=true,Tasks="padv.builtin.task.GenerateSimulinkWebView")

Scope

FilterArtifact — Artifacts to run

string | padv.Artifact object | array of padv.Artifact objects

Artifacts to run, specified as either the full path to an artifact, relative path to an artifact, a padv.Artifact object that represents an artifact, or an array of padv.Artifact objects.

Example: fullfile("C:\","User","projectA","myModel.slx")

Example: fullfile("02_Models","AHRS_Voter","specification","AHRS_Voter.slx")

Example: padv.Artifact("sl_model_file",fullfile("02_Models","AHRS_Voter","specification","AHRS_Voter.slx"))

Data Types: string

Process — Process to run

padv.ProcessModel.DefaultProcessId (default) | character vector | string

Process to run, specified by a character vector or string.

For more information about processes, see Manage Multiple Build and Verification Workflows Using Processes. The process name is defined by the Name property of the process.

Example: "CIPipeline"

Data Types: char | string

Subprocesses — Subprocesses to run

character vector | cell array of character vectors | string | string array

Subprocesses to run, specified as a character vector, cell array of character vectors, string, or string array. The subprocess name is defined by the Name property of the subprocess.

Example: "SubprocessA"

Example: ["SubprocessA",SubprocessB"]

Data Types: char | string

Tasks — Tasks to run

character vector | cell array of character vectors | string | string array

Tasks to run, specified as a character vector, cell array of character vectors, string, or string array. The task name is defined by the Name property of the task.

Alternatively, you can specify the task iteration IDs for individual task iterations that you want to run. See generateProcessTasks and createProcessTaskID.

Note

You can only run tasks that are defined in the process model. For more information, see Overview of Process Model and Modify Default Process Model to Fit Your Process.

Example: "padv.builtin.task.GenerateSimulinkWebView"

Example: ["padv.builtin.task.GenerateSimulinkWebView","padv.builtin.task.RunModelStandards"]

Data Types: char | string

Execution

DiscardDictionaryChanges — Control whether build system discards unsaved changes to data dictionaries

logical.empty (default) | 0 (false) | 1 (true)

Control whether the build system discards unsaved changes to data dictionary files, specified as either:

• logical.empty — If MATLAB^® is in batch mode, the build system generates a warning and discards unsaved changes to data dictionaries.

• 0 (false) — The build system does not generate a warning and does not discard unsaved changes to data dictionaries.

• 1 (true) — The build system displays a message in the MATLAB Command Window and discards unsaved changes to data dictionaries without generating a warning.

Make sure your tasks save or discard changes to data dictionaries before they finish executing. You can use the close method of padv.Artifact to close and remove an artifact from the cache.

Note

If you specify the RunWithoutSaving argument as 1 (true), the runprocess function ignores the DiscardDictionaryChanges argument.

Example: true

Data Types: logical

DryRun — Validate inputs and generate representative outputs without running task

false or 0 (default) | true or 1

Validate task inputs and generate representative task outputs without actually running the tasks, specified as a numeric or logical 0 (false) or 1 (true). You can use a dry run to help make sure your tasks are set up as expected in the process model.

To have the dry run check out the licenses associated with the task, specify the runprocess argument DryRunLicenseCheckout as true.

Alternatively, you can perform dry runs from the Process Advisor app. For more information, see Dry Run Tasks to Test Process Model.

Example: true

Data Types: logical

DryRunLicenseCheckout — Dry runs check out product licenses associated with tasks in process

false or 0 (default) | true or 1

When the runprocess argument DryRunis true, dry runs check out the product licenses associated with the tasks in process, returned as a numeric or logical 1 (true) or 0 (false).

For more information on dry runs, see Dry Run Tasks to Test Process Model.

Example: true

Data Types: logical

EnableTaskLogging — Control command-line outputs from tasks

true or 1 (default) | false or 0

Control command-line outputs from tasks, specified as:

• A numeric or logical 0 (false) — Task logging is disabled.

• A numeric or logical 1 (true) — Task logging is enabled.

If the project setting SuppressOutputWhenInteractive is true and MATLAB is not running in batch mode, task logging is automatically disabled.

When task logging is disabled, tasks does not output information in the MATLAB Command Window.

Example: false

Data Types: logical

ExitInBatchMode — Exit MATLAB when running in batch mode

true or 1 (default) | false or 0

Exit MATLAB when running in batch mode, specified as a numeric or logical 1 (true) or 0 (false). By default, if you are running MATLAB in batch mode and runprocess finishes running, runprocess exits MATLAB.

The process exit codes are:

• 0 if the Status of buildResult is PASS

• 1 if the Status of buildResult is ERROR

• 2 if the Status of buildResult is FAIL

Example: false

Data Types: logical

Force — Skip or run up-to-date task iterations

false or 0 (default) | true or 1

Skip or run up-to-date tasks, specified as a numeric or logical 0 (false) or 1 (true). By default, runprocess does not run task iterations that have up to date results.

Example: true

Data Types: logical

Isolation — Ignore predecessor tasks

false or 0 (default) | true or 1

Ignore predecessor tasks, specified as a numeric or logical 0 (false) or 1 (true).

By default, runprocess runs predecessor tasks before running the current task. Specify Isolation as true if you want to run a task in isolation, without running its predecessor tasks.

Note that you define predecessors in the process model by using either the dependsOn function or the addDependsOnRelationship function.

Example: true

Data Types: logical

MakeSureOutputArtifactsWriteable — Make sure output artifacts writeable

false (0) (default) | true (1)

Make sure output artifacts writeable, specified as a numeric or logical true (1) or false (0).

The pipeline generator uses this argument when stashing and unstashing workspace artifacts in Jenkins^®. When MakeSureOutputArtifactsWriteable is true, the build system uses the utility function padv.util.makeSureArtifactsWriteable on the task output directories.

Example: true

Data Types: logical

ReanalyzeProjectAnalysisIssues — Automatically reanalyze project analysis issues that have severity level of error

true or 1 (default) | false or 0

Automatically reanalyze project analysis issues that have a severity level of error, specified as a numeric or logical 1 (true) or 0 (false).

To prevent the build system from reanalyzing project analysis issues that have a severity level of error, you can specify ReanalyzeProjectAnalysisIssues as false. This might reduce the execution time for runprocess, but the build system might not generate the expected task iterations or detect outdated results.

Fix the issues listed in the Project Analysis Issues pane of the Process Advisor app to make sure the build system can fully analyze the project, generate the expected task iterations, and detect outdated results.

Example: false

Data Types: logical

RefreshProcessModel — Automatically refresh before running tasks

true or 1 (default) | false or 0

Automatically refresh before running tasks, specified as a numeric or logical 1 (true) or 0 (false). By default, runprocess refreshes before running tasks so that the run uses the current state of the process model and project. If you specify RefreshProcessModel as false, runprocess does not refresh before running, but the run might not include the latest changes to tasks in the process model or artifacts in the project.

Example: false

Data Types: logical

RerunErroredTasks — Rerun errored task iterations

false or 0 (default) | true or 1

Rerun errored task iterations, specified as a numeric or logical 0 (false) or 1 (true).

Example: true

Data Types: logical

RerunFailedTasks — Rerun failed task iterations

false or 0 (default) | true or 1

Rerun failed task iterations, specified as a numeric or logical 0 (false) or 1 (true).

Example: true

Data Types: logical

RunWithoutSaving — Allow build to run with dirty project artifacts

0 (false) (default) | 1 (true)

Allow build to run with dirty project artifacts, specified as a numeric or logical 0 (false) or 1 (true).

Only specify this argument as 1 (true) if you are sure that your task inputs and dependencies are not impacted by the unsaved artifacts. Running without saving means the build system ignores unsaved changes, which can lead to invalid task results and possible tool errors when running tasks.

If you specify the RunWithoutSaving argument as 1 (true), the runprocess function ignores the DiscardDictionaryChanges argument and does not save or discard changes to data dictionary files.

Example: true

Data Types: logical

Reporting and Output

GenerateJUnitForProcess — Generate JUnit-style XML report for process

false or 0 (default) | true or 1

Generate JUnit-style XML report for each task in process, specified as a numeric or logical 0 (false) or 1 (true).

Example: true

Data Types: logical

GenerateReport — Automatically generate report at end of runprocess

false or 0 (default) | true or 1

Automatically generate report after runprocess runs tasks, specified as a numeric or logical 1 (true) or 0 (false).

Example: runprocess(GenerateReport = true)

Data Types: logical

ReportFormat — File format for generated report

"pdf" (default) | "html" | "html-file" | "docx"

File format for the generated report, specified as one of these values:

• "pdf" — PDF file

• "html" — HTML report, packaged as a zipped file that contains the HTML file, images, style sheet, and JavaScript^® files of the report

• "html-file" — HTML report

• "docx" — Microsoft^® Word document

Note that for the runprocess function to generate a report, you must also specify the argument GenerateReport as true.

Example: runprocess(GenerateReport = true,ReportFormat = "html-file")

ReportPath — Name and path of generated report

"ProcessAdvisorReport" (default) | string array

Name and path of generated report, specified as a string array.

Note that for the runprocess function to generate a report, you must also specify the argument GenerateReport as true.

Example: runprocess(GenerateReport = true,ReportPath = fullfile(pwd,"folderName","reportName"))

Data Types: string

SuppressOutputWhenInteractive — Suppress command-line output from Process Advisor

logical.empty (default) | 1 or true | 0 or false

Suppress command-line output from Process Advisor during interactive MATLAB sessions, specified as either:

• An empty logical array (logical.empty) — No impact. runprocess follows the Process Advisor setting Suppress outputs to command window.

• A numeric or logical 1 (true) — Override the Process Advisor setting Suppress outputs to command window and suppress output to the MATLAB Command Window.

• A numeric or logical 0 (false) — Override the Process Advisor setting Suppress outputs to command window and show build logs and task execution messages in the MATLAB Command Window.

Note that this argument has no impact when you run MATLAB in batch mode, which is typically the case for CI systems.

Example: true

Data Types: logical

Output Arguments

buildResult — Results of run

padv.BuildResult

Results of run, returned as a padv.BuildResult object.

The padv.BuildResult object includes:

• The start time and end time of the run

• The status of the run (Pass,Error,Fail)

• Lists of the tasks that the passed, generated errors, were skipped, or failed during the run

• Input arguments to the run

exitCode — Exit code from run

0 | 1 | 2

Exit code from run, returned as a double representing the process error code.

• 0 if the Status of the buildResult is Pass

• 1 if the Status of the buildResult is Error

• 2 if the Status of the buildResult is Fail

Alternative Functionality

App

You can also use the Process Advisor app to run each task or individual task iterations in the process. To open the Process Advisor app for a project, in the MATLAB Command Window, enter:

processAdvisorWindow