padv.pipeline.JenkinsOptions
Options for generating pipeline configuration file for Jenkins
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
Description
returns configuration options for generating a Jenkins pipeline configuration file.options
= padv.pipeline.JenkinsOptions
sets properties using one or more name-value arguments. For example,
options
= padv.pipeline.JenkinsOptions(Name=Value
)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
AgentLabel
— Which Jenkins agent executes pipeline tasks in Jenkins environment
"any"
(default) | string | string array
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(
block of the
parent pipeline file. For more information, see Integrate Process into Jenkins.'labelName'
)
Example: options =
padv.pipeline.JenkinsOptions(AgentLabel="high_memory")
Data Types: string
EnableArtifactCollection
— When to collect build artifacts
"always"
, 1
, or
true
(default) | "never"
, 0
, or
false
| "on_success"
| "on_failure"
When to collect build artifacts, specified as:
"never"
,0
, orfalse
— Never collect artifacts"on_success"
— Only collect artifacts when the pipeline succeeds"on_failure"
— Only collect artifacts when the pipeline fails"always"
,1
, ortrue
— 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
ArtifactZipFileName
— Name of ZIP file for job artifacts
"padv_artifacts.zip"
(default) | 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
GeneratedJenkinsFileName
— File name of generated Jenkins pipeline file
"simulink_pipeline"
(default) | 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
UseMatlabPlugin
— Specify whether Jenkins uses MATLAB® Plugin to launch MATLAB
1
(true
) (default) | 0
(false
)
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
ShellEnvironment
— Shell environment Jenkins uses to launch MATLAB
""
(default) | string
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
UseSameExecutorForSequentialStages
— Use same executor for sequential stages
true
(1
) (default) | false
(0
)
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 parentJenkinsfile
, the sequential stages uses the same executor that you defined in the top-levelnode
block of the parentJenkinsfile
. 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(
block in the
parent pipeline file. For more information, see Integrate Process into Jenkins.'labelName'
)
Example: false
Data Types: logical
RunprocessCommandOptions
— Options for runprocess
command
padv.pipeline.RunProcessOptions
(default) | padv.pipeline.RunProcessOptions
object
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)
PipelineArchitecture
— Number of stages and grouping of tasks in CI pipeline
padv.pipeline.Architecture.SingleStage
(default) | padv.pipeline.Architecture.SerialStages
| padv.pipeline.Architecture.SerialStagesGroupPerTask
| padv.pipeline.Architecture.IndependentModelPipelines
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.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.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.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.
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 the error Method too large
, consider
simplifying the pipeline architecture to use the SingleStage
architecture instead.
Example: padv.pipeline.JenkinsOptions(PipelineArchitecture =
padv.pipeline.Architecture.SerialStages)
MatlabLaunchCmd
— Command to start MATLAB program
"matlab"
(default) | string
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
MatlabStartupOptions
— Command-line startup options for MATLAB
"-nodesktop -logfile output.log"
(default) | 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
AddBatchStartupOption
— Specify whether to open MATLAB using -batch
startup option
1
(true
) (default) | 0
(false
)
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
GeneratedPipelineDirectory
— Specify where the generated pipeline file generates
fullfile("derived","pipeline")
(default) | string
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
GenerateReport
— Generate Process Advisor build report
true
or 1
(default) | false
or 0
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
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
Example: padv.pipeline.JenkinsOptions(ReportFormat =
"html-file")
ReportPath
— Name and path of generated report
"$PROJECTROOT$/ProcessAdvisorReport"
(default) | string array
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
StopOnStageFailure
— Stop running pipeline after stage fails
0
(false
) (default) | 1
(true
)
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
CheckOutdatedResultsAfterMerge
— Check for outdated results after merge
1
(true
) (default) | 0
(false
)
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
EnablePipelineCaching
— Enable pipeline caching to support incremental builds in CI
1
(true
) (default) | 0
(false
)
Enable pipeline caching to support incremental builds in CI, specified as a numeric
or logical 0
(false
) or 1
(true
).
By default, generated pipelines use caching to help the performance of incremental
builds in CI. However, if a generated pipeline generates errors
when merging artifact information from parallel jobs,
you can disable pipeline caching by specifying
EnablePipelineCaching
as 0
(false
). Disabling pipeline caching increases build times, but can
help avoid merge
conflicts.
Example: false
Data Types: logical
Examples
Specify Jenkins Configuration Options When Generating Pipeline Configuration File
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.
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 (한국어)