padv.pipeline.RunProcessOptions

Options for how generated pipeline files run processes

expand all in page

    Description

    Use the padv.pipeline.RunProcessOptions object to specify how your generated pipeline files invoke the runprocess function. The object represents the name-value arguments for the runprocess function. You pass this object to the RunprocessCommandOptions argument of your pipeline generator options object when generating pipeline files using the pipeline generator. The pipeline generator, padv.pipeline.generatePipeline, uses your RunProcessOptions object to determine how to invoke the runprocess function in the CI pipeline files for your CI platform.

    Creation

    Syntax

    options = padv.pipeline.RunProcessOptions()

    Description

    options = padv.pipeline.RunProcessOptions() creates an options object that specifies how generated pipeline files invoke the runprocess function.

    The object has properties for each of the name-value arguments in the runprocess function, except for the arguments Tasks, Process, Subprocesses, and FilterArtifact.

    example

    Properties

    expand all

    Execution

    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 property as 1 (true), the runprocess function ignores the DiscardDictionaryChanges property.

    Example: true

    Data Types: logical

    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 property DryRunLicenseCheckout as true.

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

    Example: true

    Data Types: logical

    When the property 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

    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

    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

    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

    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

    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

    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

    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

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

    Example: true

    Data Types: logical

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

    Example: true

    Data Types: logical

    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 property as 1 (true), the runprocess function ignores the DiscardDictionaryChanges property and does not save or discard changes to data dictionary files.

    Example: true

    Data Types: logical

    Reporting and Output

    Enable integration with OpenTelemetry to view detailed pipeline timing and execution data, specified as a numeric or logical true (1) or false (0).

    Before you enable the OpenTelemetry integration, you must install the OpenTelemetry-MATLAB package and set up OpenTelemetry, as shown in Collect Detailed Execution Data with OpenTelemetry Integration.

    Data Types: logical

    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

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

    Data Types: logical

    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 property GenerateReport as true.

    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 property GenerateReport as true.

    Data Types: string

    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

    Manage Task States and Outputs

    Clean task results, specified as a numeric or logical 1 (true) or 0 (false).

    Data Types: logical

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

    When you specify the properties Clean and DeleteOutputs as true, runprocess clean task results and deletes the task outputs specified by the OutputPaths property of padv.TaskResult objects. The OutputDirectory of a task might still contain files.

    Data Types: logical

    Mark task results as outdated, specified as a numeric or logical 1 (true) or 0 (false).

    Data Types: logical

    Examples

    collapse all

    To control how generated pipelines invoke the runprocess function, you can create a padv.pipeline.RunProcessOptions object, specify the object properties, and pass the object to the pipeline generator options object for your CI platform. This example shows how to force each task in a generated pipeline to run, even if the tasks are already up-to-date.

    Create a RunProcessOptions object.

    rpo = padv.pipeline.RunProcessOptions;

    Force tasks to run by specifying the Force property as true.

    rpo.Force = true;

    Create the pipeline generator options object for your CI platform. There are pipeline generator options objects available for Azure® DevOps, GitHub®, GitLab®, and Jenkins.

    For example, to use Azure DevOps with pipeline generator version 2:

    op = padv.pipeline.AzureDevOpsOptions(GeneratorVersion=2);

    Pass the RunProcessOptions object to the RunprocessCommandOptions argument of the pipeline generator options object.

    op.RunprocessCommandOptions = rpo;

    Set the additional required properties for your pipeline generator options object and generate your pipeline. For example:

    op.SupportPackageRoot = 'C:/ProgramData/MATLAB/SupportPackages/R2025a';
op.NetworkStoragePath = '/artifactManagement/cacheStorage';
padv.pipeline.generatePipeline(op)

    For Azure DevOps, the generated pipeline file, simulink_pipeline.yml, includes a call to the runprocess function that specifies the Force argument of runprocess as true as specified by the RunProcessOptions object.

    - script:
    >
    matlab  -nodesktop  -logfile output.log  -batch "openProject(pwd);runprocess(Process = 'CIPipeline', Force = true...

    See Also

    Functions

    Objects

    Topics