runprocess

Generate and run pipeline of tasks by using build system

Syntax

[buildResult,exitCode] = runprocess()

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

Description

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

This function requires CI/CD Automation for Simulink Check.

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

Examples

Run MBD Pipeline

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

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

processAdvisorExampleStart

Generate and run the MBD 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.

Input Arguments

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: [buildResult,exitCode] = runprocess(Force=true)

Tasks — Names of tasks that you want to run

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

Names of tasks that you want 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

Process — Name of process that you want to run

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

Name of process that you want to run, specified by a character vector or string.

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

Example: "CIPipeline"

Data Types: char | string

Subprocesses — Names of subprocesses that you want to run

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

Names of subprocesses that you want 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

FilterArtifact — Artifacts that you want to run tasks for

string.empty (default) | string | padv.Artifact object | array of padv.Artifact objects

Artifact or artifacts that you want to run tasks for, 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

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 — Include task dependencies

false or 0 (default) | true or 1

Include task dependencies, specified as a numeric or logical 0 (false) or 1 (true).

By default, runprocess includes task dependencies when running a task. Specify Isolation as true if you want to run a task in isolation, without running task dependencies.

Note that you define task dependencies in the process model by using the function dependsOn.

Example: true

Data Types: logical

Clean — Clear task results and delete outputs

false or 0 (default) | true or 1

Clear task results and delete task outputs, specified as a numeric or logical 0 (false) or 1 (true).

If you specify Clean as true:

• The runprocess functions ignores other name-value arguments, cleans the task results, and deletes task outputs.

• The OutputDirectory of the task might still contain files. The runprocess function only deletes the task outputs, specified by the OutputPaths property of the padv.TaskResult object for the task.

• You cannot specify MarkStale as true. The arguments are mutually exclusive.

Example: true

Data Types: logical

DeleteOutputs — Delete task outputs

false or 0 (default) | true or 1

Delete task outputs, specified as a numeric or logical 0 (false) or 1 (true).

Note

To delete task outputs with DeleteOutputs, you must specify Clean as true.

Example: true

Data Types: logical

MarkStale — Mark task as outdated

false or 0 (default) | true or 1

Mark task as outdated, specified as a numeric or logical 0 (false) or 1 (true). When you mark a task as stale, the results appear outdated in the Process Advisor app.

Note

If you specify MarkStale as true, then you cannot specify Clean as true. The arguments are mutually exclusive.

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

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

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

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

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

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

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

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

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

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

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.

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

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