Main Content

padv.pipeline.JenkinsOptions

Options for generating pipeline configuration file for Jenkins

expand all in page

    Description

    This object requires CI/CD Automation for Simulink Check. Use the padv.pipeline.JenkinsOptions object to represent the desired options for generating a Jenkins® pipeline configuration file. To generate a Jenkins pipeline configuration file, use padv.pipeline.JenkinsOptions as an input argument to the padv.pipeline.generatePipeline function. For information on how to use the pipeline generator to integrate into a Jenkins CI system, see Integrate Process into Jenkins.

    Creation

    Syntax

    options = padv.pipeline.JenkinsOptions
    options = padv.pipeline.JenkinsOptions(Name=Value)

    Description

    options = padv.pipeline.JenkinsOptions returns configuration options for generating a Jenkins pipeline configuration file.

    example

    options = padv.pipeline.JenkinsOptions(Name=Value) sets properties using one or more name-value arguments. For example, padv.pipeline.JenkinsOptions(PipelineArchitecture = padv.pipeline.Architecture.SerialStagesGroupPerTask) creates an object that specifies that a generated pipeline configuration file use an agent with the label high_memory.

    Properties

    expand all

    Which Jenkins agent executes pipeline tasks in the Jenkins environment, specified as a string or string array.

    Use this property to specify the Jenkins agent that executes all stages in the pipeline. Jenkins agents are typically either a machine or a container. For more information, see the Glossary in the Jenkins documentation.

    Note

    When the UseSameExecutorForSequentialStages property is true, the pipeline generator ignores the AgentLabel property since the sequential stages use the same agent as the parent pipeline. You specify the agent in the node('labelName') block of the parent pipeline file. For more information, see Integrate Process into Jenkins.

    Example: options = padv.pipeline.JenkinsOptions(AgentLabel="high_memory")

    Data Types: string

    When to collect build artifacts, specified as:

    • "never", 0, or false — Never collect artifacts

    • "on_success" — Only collect artifacts when the pipeline succeeds

    • "on_failure" — Only collect artifacts when the pipeline fails

    • "always", 1, or true — Always collect artifacts

    If you choose to collect artifacts, the child pipeline contains a job, Collect_Artifacts, that collects the build artifacts and attaches the artifacts to the Collect_Artifacts job.

    This property uses the Jenkins Core Plugin to add an "archiveArtifacts" step in the generated Jenkinsfile that defines the Jenkins pipeline. Install the Jenkins Core Plugin before you specify EnableArtifactCollection. For more information, see the Jenkins documentation for "archiveArtifacts": https://www.jenkins.io/doc/pipeline/steps/core/#archiveartifacts-archive-the-artifacts.

    Example: padv.pipeline.JenkinsOptions(EnableArtifactCollection="on_failure")

    Data Types: logical | string

    Name of ZIP file for job artifacts, specified as a string.

    This property specifies the file name that appears next to the "artifacts" for the "archiveArtifacts" step in the generated Jenkinsfile that defines the Jenkins pipeline.

    For more information, see the Jenkins documentation for "archiveArtifacts": https://www.jenkins.io/doc/pipeline/steps/core/#archiveartifacts-archive-the-artifacts.

    Example: padv.pipeline.JenkinsOptions(ArtifactZipFileName = "my_job_artifacts.zip")

    Data Types: string

    File name of generated Jenkins pipeline file, specified as a string.

    By default, the generated pipeline generates into the subfolder derived > pipeline, relative to the project root. To change where the pipeline file generates, specify GeneratedPipelineDirectory.

    Example: padv.pipeline.JenkinsOptions(GeneratedJenkinsFileName = "padv_generated_pipeline_file")

    Data Types: string

    Specify whether Jenkins uses MATLAB Plugin to launch MATLAB, specified as a numeric or logical 0 (false) or 1 (true).

    If the property UseMatlabPlugin is true, Jenkins uses the "runMATLABCommand" step to launch MATLAB and the pipeline generator ignores the properties MatlabLaunchCmd and MatlabStartupOptions. For more information, see the Jenkins documentation for "runMATLABCommand": https://www.jenkins.io/doc/pipeline/steps/matlab/#runmatlabcommand-run-matlab-commands-scripts-or-functions

    If the property UseMatlabPlugin is false, Jenkins uses the specified ShellEnvironment to launch MATLAB and uses the options specified by the properties MatlabLaunchCmd and MatlabStartupOptions.

    Using the MATLAB Plugin for Jenkins is recommended. For more information, see https://plugins.jenkins.io/matlab/.

    Example: padv.pipeline.JenkinsOptions(UseMatlabPlugin = false)

    Data Types: logical

    Shell environment Jenkins uses to launch MATLAB, specified as one of these values:

    • "bat" — Windows® batch script

    • "sh" — Shell script

    • "pwsh" — PowerShell Core script

    • "powershell" — Windows PowerShell script

    • "" — Automatically use "bat" or "sh" based on the platform where pipeline generation runs

    If the property UseMatlabPlugin is true, Jenkins uses the "runMATLABCommand" step to launch MATLAB and the pipeline generator ignores the properties MatlabLaunchCmd and MatlabStartupOptions. For more information, see the Jenkins documentation for "runMATLABCommand": https://www.jenkins.io/doc/pipeline/steps/matlab/#runmatlabcommand-run-matlab-commands-scripts-or-functions

    If the property UseMatlabPlugin is false, Jenkins uses the specified ShellEnvironment to launch MATLAB and uses the options specified by the properties MatlabLaunchCmd and MatlabStartupOptions.

    Example: padv.pipeline.JenkinsOptions(UseMatlabPlugin = false, ShellEnvironment = "bat")

    Data Types: string

    Use same executor for sequential stages, specified as either a numeric or logical:

    • true (1) — By default, the pipeline generator configures the pipeline to use the same executor for sequential stages. This approach minimizes the number of executors required by the generated pipeline and allows the stages to use the same workspace. If you are automatically generating your Jenkins pipeline from a parent Jenkinsfile, the sequential stages uses the same executor that you defined in the top-level node block of the parent Jenkinsfile. For an example, see Integrate Process into Jenkins.

    • false (0) — The pipeline generator configures the pipeline to allow Jenkins to release the current agent and potentially use different agents for subsequent stages. This approach can lead to smaller, more manageable jobs, but can require additional pipeline execution time. Since different agents can use different workspaces, the pipeline generator stores the outputs from each stage and passes those outputs to the subsequent stages.

    For more information on sequential stages, see the Jenkins documentation for Sequential Stages.

    Note

    When UseSameExecutorForSequentialStages is true, the pipeline generator ignores the AgentLabel property. Sequential stages use the same agent as the parent pipeline, which you define in the node('labelName') block in the parent pipeline file. For more information, see Integrate Process into Jenkins.

    Example: false

    Data Types: logical

    Options for runprocess command, specified as a padv.pipeline.RunProcessOptions object. padv.pipeline.RunProcessOptions has properties for the name-value arguments in the runprocess function, except for the arguments Tasks, Process, Subprocesses, and FilterArtifact.

    For example, to have the pipeline generator use a command like runprocess(DryRun = true) in Jenkins, you can create a padv.pipeline.RunProcessOptions object, specify the property values, and pass the object to padv.pipeline.GitLabOptions:

    rpo = padv.pipeline.RunProcessOptions;
rpo.DryRun = true;
jo = padv.pipeline.JenkinsOptions(RunprocessCommandOptions = rpo);

    Note

    The GenerateJUnitForProcess property in padv.pipeline.RunProcessOptions is set to false by default. Previously, in padv.pipeline.JenkinsOptions, this property was true by default. The GenerateJUnitForProcess property in padv.pipeline.JenkinsOptions will be removed in a future release. Make sure to specify the GenerateJUnitForProcess property in padv.pipeline.RunProcessOptions to the value that you want the pipeline to use.

    Example: padv.pipeline.JenkinsOptions(RunprocessCommandOptions = padv.pipeline.RunProcessOptions)

    Number of stages and grouping of tasks in CI pipeline, specified as either:

    • padv.pipeline.Architecture.SingleStage — The pipeline has a single stage, named Runprocess, that runs each of the tasks in the process. This pipeline architecture requires at least one Jenkins executor. For information on defining Jenkins executors, see the Jenkins documentation for Managing Nodes.

      Example pipeline graphic that shows one stage that runs all tasks on all models

    • padv.pipeline.Architecture.SerialStages — The pipeline has one stage for each task iteration in the process. This pipeline architecture requires at least one Jenkins executor. For information on defining Jenkins executors, see the Jenkins documentation for Managing Nodes.

      Example pipeline graphic that shows one stage that runs TaskA on ModelA, one stage that runs TaskA on ModelB, one stage that runs TaskB on ModelA, and one stage that runs TaskB on ModelB

    • padv.pipeline.Architecture.SerialStagesGroupPerTask — The pipeline has one stage for each task in the process. This pipeline architecture requires at least one Jenkins executors. For information on defining Jenkins executors, see the Jenkins documentation for Managing Nodes.

      Example pipeline graphic that shows one stage that runs one task, TaskA, and one stage that runs another task, TaskB

    • padv.pipeline.Architecture.IndependentModelPipelines— The pipeline contains parallel, downstream pipelines for each model. Each downstream pipeline independently runs the tasks associated with that model. This pipeline architecture requires at least two executors. For information on defining Jenkins executors, see the Jenkins documentation for Managing Nodes.

      Example pipeline graphic showing two parallel downstream pipelines. One pipeline that runs TaskA and TaskB on ModelA. One pipeline that runs TaskA and TaskB on ModelB.

    For more information, see Integrate Process into Jenkins.

    Note

    If you choose a pipeline architecture other than SingleStage, the pipeline generator can create complex Jenkinsfile files that exceed size limits. If Jenkins generates an error that the method code in the generated Jenkinsfile is too large, consider simplifying the pipeline architecture to use the SingleStage architecture instead.

    Example: padv.pipeline.JenkinsOptions(PipelineArchitecture = padv.pipeline.Architecture.SerialStages)

    Command to start MATLAB program, specified as a string.

    Use this property to specify how the pipeline starts the MATLAB program. This property defines how the generated pipeline file launches MATLAB.

    Example: padv.pipeline.JenkinsOptions(MatlabLaunchCmd = "matlab")

    Data Types: string

    Command-line startup options for MATLAB, specified as a string.

    Use this property to specify the command-line startup options that the pipeline uses when starting the MATLAB program. This property defines the command-line startup options that appear next to the -batch option and MatlabLaunchCmd value in the"script" section of the generated pipeline file. The pipeline starts MATLAB with the specified startup options.

    By default, the support package launches MATLAB using the -batch option. If you need to run MATLAB without the -batch option, specify the property AddBatchStartupOption as false.

    Note

    If you run MATLAB using the -nodisplay option, you should set up a virtual display server before you include the following built-in tasks in your process model:

    • Generate SDD Report

    • Generate Simulink Web View

    • Generate Model Comparison

    For information, see Set Up Virtual Display Machines Without Displays.

    Example: padv.pipeline.JenkinsOptions(MatlabStartupOptions = "-nodesktop -logfile mylogfile.log")

    Data Types: string

    Specify whether to open MATLAB using -batch startup option, specified as a numeric or logical 0 (false) or 1 (true).

    By default, the support package launches MATLAB in CI using the -batch startup option.

    If you need to launch MATLAB with options that are not compatible with -batch, specify AddBatchStartupOption as false.

    Example: padv.pipeline.JenkinsOptions(AddBatchStartupOption = false)

    Data Types: logical

    Specify where the generated pipeline file generates, specified as a string.

    This property defines the directory where the generated pipeline file generates.

    By default, the generated pipeline file is named "simulink_pipeline". To change the name of the generated pipeline file, specify GeneratedJenkinsFileName.

    Example: padv.pipeline.JenkinsOptions(GeneratedPipelineDirectory = fullfile("derived","pipeline","test"))

    Data Types: string

    Generate Process Advisor build report, specified as a numeric or logical 1 (true) or 0 (false).

    Example: padv.pipeline.JenkinsOptions(GenerateReport = 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

    Example: padv.pipeline.JenkinsOptions(ReportFormat = "html-file")

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

    By default, the report path uses a relative path to the project root and the pipeline generator generates a report ProcessAdvisorReport.pdf.

    Example: padv.pipeline.JenkinsOptions(ReportFormat = "myReport")

    Data Types: string

    Stop running pipeline after stage fails, specified as a numeric or logical 0 (false) or 1 (true).

    By default, the pipeline continues to run, even if a stage in the pipeline fails.

    Example: padv.pipeline.JenkinsOptions(StopOnStageFailure = true)

    Data Types: logical

    Check for outdated results after merge, specified as a numeric or logical 1 (true) or 0 (false).

    The pipeline generator no longer uses this property.

    Example: false

    Data Types: logical

    Examples

    collapse all

    Create a padv.pipeline.JenkinsOptions object and change the options. When you generate a pipeline configuration file, the file uses the specified options.

    This example shows how to use the pipeline generator API. For information on how to use the pipeline generator to integrate into a Jenkins CI system, see Integrate Process into Jenkins.

    Load a project. For this example, you can load a Process Advisor example project. In the MATLAB Command Window, enter:

    processAdvisorExampleStart

    Create a padv.pipeline.JenkinsOptions object for generating a Jenkins pipeline configuration file. For example, specify that the pipeline run inside a single stage by using the PipelineArchitecture property.

    JenkinsOptions = padv.pipeline.JenkinsOptions(...
PipelineArchitecture = padv.pipeline.Architecture.SingleStage);

    Generate a Jenkins pipeline configuration file by using the function padv.pipeline.generatePipeline with the specified options.

    padv.pipeline.generatePipeline(JenkinsOptions);

    Note

    Calling padv.pipeline.generatePipeline(JenkinsOptions) is equivalent to calling padv.pipeline.generateJenkinsPipeline(JenkinsOptions).

    By default, the generated pipeline file is named simulink_pipeline and is saved in the derived > pipeline folder, relative to the project root. To change the name of the generated pipeline file, specify the argument GeneratedJenkinsFileName for padv.pipeline.JenkinsOptions. To change where the pipeline file generates, specify the argument GeneratedPipelineDirectory.

    For information on how to use the pipeline generator to integrate into a Jenkins CI system, see Integrate Process into Jenkins.

    See Also

    Topics