runprocess
Generate and run pipeline of tasks by using build system
Description
[
generate a model-based design (MBD) pipeline and run the pipeline using the build system.
The process model (buildResult
,exitCode
] = runprocess()processmodel.p
or processmodel.m
)
defines the tasks for the pipeline.
This function requires CI/CD Automation for Simulink Check.
[
specifies how the MBD pipeline runs using one or more buildResult
,exitCode
] = runprocess(Name=Value
)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
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)
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)
FilterArtifact
— Artifacts that you want to run tasks for
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
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
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
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. Therunprocess
function only deletes the task outputs, specified by theOutputPaths
property of thepadv.TaskResult
object for the task.You cannot specify
MarkStale
astrue
. 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
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 DryRun
is
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 theStatus
ofbuildResult
isPASS
1
if theStatus
ofbuildResult
isERROR
2
if theStatus
ofbuildResult
isFAIL
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
— 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
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
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
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
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 theStatus
of thebuildResult
isPass
1
if theStatus
of thebuildResult
isError
2
if theStatus
of thebuildResult
isFail
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
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)
Asia Pacific
- Australia (English)
- India (English)
- New Zealand (English)
- 中国
- 日本Japanese (日本語)
- 한국Korean (한국어)