Use CircleCI version 2.1 at the top of your .circleci/config.yml file.
1
version: 2.1
Add the orbs
stanza below your version, invoking the orb:
1
2
orbs:
matlab: mathworks/matlab@1.5.0
Use matlab
elements in your existing workflows and jobs.
Opt-in to use of uncertified orbs on your organization’s Security settings page.
Run a build using the MATLAB build tool.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
version: '2.1'
orbs:
matlab: mathworks/matlab@1
jobs:
build:
machine:
image: ubuntu-2204:2024.01.1
steps:
- checkout
- matlab/install
- matlab/run-build:
tasks: test
workflows:
build:
jobs:
- build
Run a MATLAB script in your project.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
version: '2.1'
orbs:
matlab: mathworks/matlab@1
jobs:
build:
machine:
image: ubuntu-2204:2024.01.1
steps:
- checkout
- matlab/install
- matlab/run-command:
command: myscript
workflows:
build:
jobs:
- build
Run all tests in your project and produce test results in JUnit-style XML format.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
version: '2.1'
orbs:
matlab: mathworks/matlab@1
jobs:
build:
machine:
image: ubuntu-2204:2024.01.1
steps:
- checkout
- matlab/install:
products: Simulink Simulink_Test
- matlab/run-tests:
test-results-junit: test-results/matlab/results.xml
- store_test_results:
path: test-results
workflows:
build:
jobs:
- build
Install a specific release of MATLAB. If you do not specify a release, the command installs the latest release of MATLAB. As part of the installation process, the command prepends MATLAB to the `PATH` system environment variable.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
no-output-timeout | Elapsed time the command can run without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”. The default is 10 minutes and the maximum is governed by the maximum time a job is allowed to run.
| No | 10m | string |
products | Products to install in addition to MATLAB, specified as a list of product names separated by spaces. You can specify this parameter to install most MathWorks products and support packages. The command uses MATLAB Package Manager (`mpm`) to install products. If you use this parameter to install transformation products, such as MATLAB Coder and MATLAB Compiler, the command does not automatically license such products for you. For a list of supported products and their correctly formatted names, see https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md#product-installation-options.
| No | '' | string |
release | MATLAB release to install. You can specify R2021a or a later release. If you do not specify `release`, the command installs the latest release of MATLAB.
| No | latest | string |
Run a build using the MATLAB build tool. Use this command to run the tasks specified in a file named `buildfile.m` in the root of your repository. To use the `run-build` command, you need MATLAB R2022b or a later release.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
build-options | MATLAB build options, specified as a list of options separated by spaces. The command supports the same options that you can pass to the `buildtool` command when running a MATLAB build. For more information, see https://www.mathworks.com/help/matlab/ref/buildtool.html.
| No | '' | string |
no-output-timeout | Elapsed time the command can run without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”. The default is 10 minutes and the maximum is governed by the maximum time a job is allowed to run.
| No | 10m | string |
startup-options | MATLAB startup options, specified as a list of options separated by spaces. For more information about startup options, see https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html.
| No | '' | string |
tasks | Tasks to run, specified as a list of task names separated by spaces. If a task accepts arguments, enclose them in parentheses. If you do not specify `tasks`, the command runs the default tasks in `buildfile.m` as well as all the tasks on which they depend. MATLAB exits with exit code 0 if the tasks run without error. Otherwise, MATLAB terminates with a nonzero exit code, which causes the command to fail.
| No | '' | string |
Run MATLAB scripts, functions, and statements. When you use this command, all of the required files must be on the MATLAB search path.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
command | Script, function, or statement to execute. If the value of `command` is the name of a MATLAB script or function, do not specify the file extension. If you specify more than one script, function, or statement, use a comma or semicolon to separate them. MATLAB exits with exit code 0 if the specified script, function, or statement executes successfully without error. Otherwise, MATLAB terminates with a nonzero exit code, which causes the command to fail. To fail the command in certain conditions, use the `assert` or `error` function.
| Yes | - | string |
no-output-timeout | Elapsed time the command can run without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”. The default is 10 minutes and the maximum is governed by the maximum time a job is allowed to run.
| No | 10m | string |
startup-options | MATLAB startup options, specified as a list of options separated by spaces. For more information about startup options, see https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html.
| No | '' | string |
Run MATLAB and Simulink tests and generate artifacts. By default, the command includes any files in your project that have a `Test` label. If your pipeline does not use a MATLAB project, or if it uses a MATLAB release before R2019a, then the command includes all tests in the root of your repository and in any of its subfolders. The command fails if any of the included tests fail.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
code-coverage-cobertura | Path to write the code coverage results in Cobertura XML format.
| No | '' | string |
code-coverage-html | Path to write the code coverage results in HTML format.
| No | '' | string |
logging-level | Maximum verbosity level for logged diagnostics included for the test run, specified as `none`, `terse`, `concise`, `detailed`, or `verbose`. By default, the command includes diagnostics logged at the `terse` level.
| No | '' | string |
model-coverage-cobertura | Path to write the model coverage results in Cobertura XML format. This parameter requires a Simulink Coverage license and is supported in MATLAB R2018b and later.
| No | '' | string |
model-coverage-html | Path to write the model coverage results in HTML format. This parameter requires a Simulink Coverage license and is supported in MATLAB R2018b and later.
| No | '' | string |
no-output-timeout | Elapsed time the tests can run without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”. The default is 10 minutes and the maximum is governed by the maximum time a job is allowed to run.
| No | 10m | string |
output-detail | Amount of event detail displayed for the test run, specified as `none`, `terse`, `concise`, `detailed`, or `verbose`. By default, the command displays failing and logged events at the `detailed` level and test run progress at the `concise` level.
| No | '' | string |
select-by-folder | Location of the folder used to select test suite elements, relative to the project root folder. To create a test suite, MATLAB uses only the tests in the specified folder and its subfolders. You can specify multiple folders using a colon-separated or semicolon-separated list.
| No | '' | string |
select-by-tag | Test tag used to select test suite elements. To create a test suite, MATLAB uses only the test elements with the specified tag.
| No | '' | string |
source-folder | Location of the folder containing source code, relative to the project root folder. The specified folder and its subfolders are added to the top of the MATLAB search path. If you specify `source-folder` and then generate a coverage report, MATLAB uses only the source code in the specified folder and its subfolders to generate the report. You can specify multiple folders using a colon-separated or semicolon-separated list.
| No | '' | string |
startup-options | MATLAB startup options, specified as a list of options separated by spaces. For more information about startup options, see https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html.
| No | '' | string |
strict | Option to apply strict checks when running tests, specified as `false` or `true`. If you specify a value of `true`, the command generates a qualification failure whenever a test issues a warning.
| No | false | boolean |
test-results-html | Path to write the test results in HTML format.
| No | '' | string |
test-results-junit | Path to write the test results in JUnit-style XML format.
| No | '' | string |
test-results-pdf | Path to write the test results in PDF format. On macOS platforms, this parameter is supported in MATLAB R2020b and later.
| No | '' | string |
test-results-simulink-test | Path to export Simulink Test Manager results in MLDATX format. This parameter requires a Simulink Test license and is supported in MATLAB R2019a and later.
| No | '' | string |
use-parallel | Option to run tests in parallel, specified as `false` or `true`. If the test runner configuration is suited for parallelization, you can specify a value of `true` to run tests in parallel. This parameter requires a Parallel Computing Toolbox license.
| No | false | boolean |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
# This code is licensed from CircleCI to the user under the MIT license.
# See here for details: https://circleci.com/developer/orbs/licensing
version: 2.1
description: |
Run MATLAB as part of your build pipeline.
display:
home_url: https://www.mathworks.com/solutions/continuous-integration.html
source_url: https://github.com/mathworks/matlab-circleci-orb
commands:
install:
description: |
Install a specific release of MATLAB. If you do not specify a release, the command installs the latest release of MATLAB. As part of the installation process, the command prepends MATLAB to the `PATH` system environment variable.
parameters:
no-output-timeout:
default: 10m
description: |
Elapsed time the command can run without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”. The default is 10 minutes and the maximum is governed by the maximum time a job is allowed to run.
type: string
products:
default: ""
description: |
Products to install in addition to MATLAB, specified as a list of product names separated by spaces. You can specify this parameter to install most MathWorks products and support packages. The command uses MATLAB Package Manager (`mpm`) to install products. If you use this parameter to install transformation products, such as MATLAB Coder and MATLAB Compiler, the command does not automatically license such products for you. For a list of supported products and their correctly formatted names, see https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md#product-installation-options.
type: string
release:
default: latest
description: |
MATLAB release to install. You can specify R2021a or a later release. If you do not specify `release`, the command installs the latest release of MATLAB.
type: string
steps:
- run:
command: "#!/bin/bash\n\n# Exit script if you try to use an uninitialized variable.\nset -o nounset\n\n# Exit script if a statement returns a non-true return value.\nset -o errexit\n\n# Use the error status of the first failure, rather than that of the last item in a pipeline.\nset -o pipefail\n\nsudoIfAvailable() {\n if command -v sudo >/dev/null 2>&1; then\n sudo -E bash \"$@\"\n else\n bash \"$@\"\n fi\n}\n\nstream() {\n local url=\"$1\"\n local status=0\n\n if command -v wget >/dev/null 2>&1; then\n wget --retry-connrefused --waitretry=5 -qO- \"$url\" || status=$?\n elif command -v curl >/dev/null 2>&1; then\n curl --retry 5 --retry-connrefused --retry-delay 5 -sSL \"$url\" || status=$?\n else\n echo \"Could not find wget or curl command\" >&2\n return 1\n fi\n\n if [ $status -ne 0 ]; then\n echo \"Error streaming file from $url\" >&2\n fi\n\n return $status\n}\n\ndownload() {\n local url=\"$1\"\n local filename=\"$2\"\n local status=0\n \n if command -v wget >/dev/null 2>&1; then\n wget --retry-connrefused --waitretry=5 -qO \"$filename\" \"$url\" 2>&1 || status=$?\n elif command -v curl >/dev/null 2>&1; then\n curl --retry 5 --retry-all-errors --retry-delay 5 -sSLo \"$filename\" \"$url\" || status=$?\n else\n echo \"Could not find wget or curl command\" >&2\n return 1\n fi\n\n if [ $status -ne 0 ]; then\n echo \"Error downloading file from $url to $filename\" >&2\n fi\n \n return $status\n}\n\nos=$(uname)\narch=$(uname -m)\nbinext=\"\"\ntmpdir=$(mktemp -d 2>/dev/null || mktemp -d -t 'install')\nrootdir=\"$tmpdir/matlab_root\"\nbatchdir=\"$tmpdir/matlab-batch\"\nmpmdir=\"$tmpdir/mpm\"\nbatchbaseurl=\"https://ssd.mathworks.com/supportfiles/ci/matlab-batch/v1\"\nmpmbaseurl=\"https://www.mathworks.com/mpm\"\n\n# resolve release\nparsedrelease=$(echo \"$PARAM_RELEASE\" | tr '[:upper:]' '[:lower:]')\nif [[ \"$parsedrelease\" = \"latest\" ]]; then\n mpmrelease=$(stream https://ssd.mathworks.com/supportfiles/ci/matlab-release/v0/latest)\nelse\n mpmrelease=\"$parsedrelease\"\nfi\n\n# validate release is supported\nif [[ \"$mpmrelease\" < \"r2020b\" ]]; then\n echo \"Release '${mpmrelease}' is not supported. Use 'R2020b' or a later release.\">&2\n exit 1\nfi\n\n# install system dependencies\nif [[ \"$os\" = \"Linux\" ]]; then\n # install MATLAB dependencies\n release=$(echo \"${mpmrelease}\" | grep -ioE \"(r[0-9]{4}[a-b])\")\n stream https://ssd.mathworks.com/supportfiles/ci/matlab-deps/v0/install.sh | sudoIfAvailable -s -- \"$release\"\n # install mpm depencencies\n sudoIfAvailable -c \"apt-get install --no-install-recommends --no-upgrade --yes \\\n wget \\\n unzip \\\n ca-certificates\"\nelif [[ \"$os\" = \"Darwin\" && \"$arch\" = \"arm64\" ]]; then\n if [[ \"$mpmrelease\" < \"r2023b\" ]]; then\n # install Rosetta 2\n sudoIfAvailable -c \"softwareupdate --install-rosetta --agree-to-license\"\n else\n # install Java runtime\n jdkpkg=\"$tmpdir/jdk.pkg\"\n download https://corretto.aws/downloads/latest/amazon-corretto-8-aarch64-macos-jdk.pkg \"$jdkpkg\"\n sudoIfAvailable -c \"installer -pkg '$jdkpkg' -target /\"\n fi\nfi\n\n# set os specific options\nif [[ \"$os\" = CYGWIN* || \"$os\" = MINGW* || \"$os\" = MSYS* ]]; then\n mwarch=\"win64\"\n binext=\".exe\"\n rootdir=$(cygpath \"$rootdir\")\n mpmdir=$(cygpath \"$mpmdir\")\n batchdir=$(cygpath \"$batchdir\")\nelif [[ \"$os\" = \"Darwin\" ]]; then\n if [[ \"$arch\" = \"arm64\" && ! \"$mpmrelease\" < \"r2023b\" ]]; then\n mwarch=\"maca64\"\n else\n mwarch=\"maci64\"\n fi\n rootdir=\"$rootdir/MATLAB.app\"\n sudoIfAvailable -c \"launchctl limit maxfiles 65536 200000\" # g3185941\nelse\n mwarch=\"glnxa64\"\nfi\n\nmkdir -p \"$rootdir\"\nmkdir -p \"$batchdir\"\nmkdir -p \"$mpmdir\"\n\n# install mpm\ndownload \"$mpmbaseurl/$mwarch/mpm\" \"$mpmdir/mpm$binext\"\nchmod +x \"$mpmdir/mpm$binext\"\n\n# install matlab-batch\ndownload \"$batchbaseurl/$mwarch/matlab-batch$binext\" \"$batchdir/matlab-batch$binext\"\nchmod +x \"$batchdir/matlab-batch$binext\"\n\n# install matlab\n\"$mpmdir/mpm$binext\" install \\\n --release=\"$mpmrelease\" \\\n --destination=\"$rootdir\" \\\n --products ${PARAM_PRODUCTS} MATLAB\n\n# add MATLAB and matlab-batch to path\necho 'export PATH=\"'$rootdir'/bin:'$batchdir':$PATH\"' >> $BASH_ENV"
environment:
PARAM_PRODUCTS: <<parameters.products>>
PARAM_RELEASE: <<parameters.release>>
name: Install MATLAB
no_output_timeout: <<parameters.no-output-timeout>>
shell: bash
run-build:
description: |
Run a build using the MATLAB build tool. Use this command to run the tasks specified in a file named `buildfile.m` in the root of your repository. To use the `run-build` command, you need MATLAB R2022b or a later release.
parameters:
build-options:
default: ""
description: |
MATLAB build options, specified as a list of options separated by spaces. The command supports the same options that you can pass to the `buildtool` command when running a MATLAB build. For more information, see https://www.mathworks.com/help/matlab/ref/buildtool.html.
type: string
no-output-timeout:
default: 10m
description: |
Elapsed time the command can run without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”. The default is 10 minutes and the maximum is governed by the maximum time a job is allowed to run.
type: string
startup-options:
default: ""
description: |
MATLAB startup options, specified as a list of options separated by spaces. For more information about startup options, see https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html.
type: string
tasks:
default: ""
description: |
Tasks to run, specified as a list of task names separated by spaces. If a task accepts arguments, enclose them in parentheses. If you do not specify `tasks`, the command runs the default tasks in `buildfile.m` as well as all the tasks on which they depend. MATLAB exits with exit code 0 if the tasks run without error. Otherwise, MATLAB terminates with a nonzero exit code, which causes the command to fail.
type: string
steps:
- run:
command: |-
#!/bin/bash
# Exit script if you try to use an uninitialized variable.
set -o nounset
# Exit script if a statement returns a non-true return value.
set -o errexit
# Use the error status of the first failure, rather than that of the last item in a pipeline.
set -o pipefail
sudoIfAvailable() {
if command -v sudo >/dev/null 2>&1; then
sudo -E bash "$@"
else
bash "$@"
fi
}
stream() {
local url="$1"
local status=0
if command -v wget >/dev/null 2>&1; then
wget --retry-connrefused --waitretry=5 -qO- "$url" || status=$?
elif command -v curl >/dev/null 2>&1; then
curl --retry 5 --retry-connrefused --retry-delay 5 -sSL "$url" || status=$?
else
echo "Could not find wget or curl command" >&2
return 1
fi
if [ $status -ne 0 ]; then
echo "Error streaming file from $url" >&2
fi
return $status
}
tmpdir=$(mktemp -d 2>/dev/null || mktemp -d -t 'run-build')
# install run-matlab-command
stream https://ssd.mathworks.com/supportfiles/ci/run-matlab-command/v2/install.sh | sudoIfAvailable -s -- "${tmpdir}/bin"
# form OS appropriate paths for MATLAB
os=$(uname)
scriptdir="$tmpdir"
binext=""
if [[ "$os" = CYGWIN* || "$os" = MINGW* || "$os" = MSYS* ]]; then
scriptdir=$(cygpath -w "$scriptdir")
binext=".exe"
fi
# create buildtool command from parameters
buildCommand="buildtool"
if [ -n "$PARAM_TASKS" ]; then
buildCommand+=" ${PARAM_TASKS}"
fi
if [ -n "$PARAM_BUILD_OPTIONS" ]; then
buildCommand+=" ${PARAM_BUILD_OPTIONS}"
fi
# create script to execute
script="command_${RANDOM}"
scriptpath="${tmpdir}/${script}.m"
echo "cd(getenv('MW_ORIG_WORKING_FOLDER'));" > "$scriptpath"
cat \<< EOF >> "$scriptpath"
$buildCommand
EOF
# run MATLAB command
"${tmpdir}/bin/run-matlab-command$binext" "setenv('MW_ORIG_WORKING_FOLDER', cd('${scriptdir//\'/\'\'}'));$script" $PARAM_STARTUP_OPTIONS
environment:
PARAM_BUILD_OPTIONS: <<parameters.build-options>>
PARAM_STARTUP_OPTIONS: <<parameters.startup-options>>
PARAM_TASKS: <<parameters.tasks>>
name: Run MATLAB build
no_output_timeout: <<parameters.no-output-timeout>>
shell: bash
run-command:
description: |
Run MATLAB scripts, functions, and statements. When you use this command, all of the required files must be on the MATLAB search path.
parameters:
command:
description: |
Script, function, or statement to execute. If the value of `command` is the name of a MATLAB script or function, do not specify the file extension. If you specify more than one script, function, or statement, use a comma or semicolon to separate them. MATLAB exits with exit code 0 if the specified script, function, or statement executes successfully without error. Otherwise, MATLAB terminates with a nonzero exit code, which causes the command to fail. To fail the command in certain conditions, use the `assert` or `error` function.
type: string
no-output-timeout:
default: 10m
description: |
Elapsed time the command can run without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”. The default is 10 minutes and the maximum is governed by the maximum time a job is allowed to run.
type: string
startup-options:
default: ""
description: |
MATLAB startup options, specified as a list of options separated by spaces. For more information about startup options, see https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html.
type: string
steps:
- run:
command: |
#!/bin/bash
# Exit script if you try to use an uninitialized variable.
set -o nounset
# Exit script if a statement returns a non-true return value.
set -o errexit
# Use the error status of the first failure, rather than that of the last item in a pipeline.
set -o pipefail
sudoIfAvailable() {
if command -v sudo >/dev/null 2>&1; then
sudo -E bash "$@"
else
bash "$@"
fi
}
stream() {
local url="$1"
local status=0
if command -v wget >/dev/null 2>&1; then
wget --retry-connrefused --waitretry=5 -qO- "$url" || status=$?
elif command -v curl >/dev/null 2>&1; then
curl --retry 5 --retry-connrefused --retry-delay 5 -sSL "$url" || status=$?
else
echo "Could not find wget or curl command" >&2
return 1
fi
if [ $status -ne 0 ]; then
echo "Error streaming file from $url" >&2
fi
return $status
}
tmpdir=$(mktemp -d 2>/dev/null || mktemp -d -t 'run-command')
# install run-matlab-command
stream https://ssd.mathworks.com/supportfiles/ci/run-matlab-command/v2/install.sh | sudoIfAvailable -s -- "${tmpdir}/bin"
# form OS appropriate paths for MATLAB
os=$(uname)
scriptdir="$tmpdir"
binext=""
if [[ "$os" = CYGWIN* || "$os" = MINGW* || "$os" = MSYS* ]]; then
scriptdir=$(cygpath -w "$scriptdir")
binext=".exe"
fi
# create script to execute
script="command_${RANDOM}"
scriptpath="${tmpdir}/${script}.m"
echo "cd(getenv('MW_ORIG_WORKING_FOLDER'));" > "$scriptpath"
cat \<< EOF >> "$scriptpath"
${PARAM_COMMAND}
EOF
# run MATLAB command
"${tmpdir}/bin/run-matlab-command$binext" "setenv('MW_ORIG_WORKING_FOLDER', cd('${scriptdir//\'/\'\'}'));$script" $PARAM_STARTUP_OPTIONS
environment:
PARAM_COMMAND: <<parameters.command>>
PARAM_STARTUP_OPTIONS: <<parameters.startup-options>>
name: Run MATLAB command
no_output_timeout: <<parameters.no-output-timeout>>
shell: bash
run-tests:
description: |
Run MATLAB and Simulink tests and generate artifacts. By default, the command includes any files in your project that have a `Test` label. If your pipeline does not use a MATLAB project, or if it uses a MATLAB release before R2019a, then the command includes all tests in the root of your repository and in any of its subfolders. The command fails if any of the included tests fail.
parameters:
code-coverage-cobertura:
default: ""
description: |
Path to write the code coverage results in Cobertura XML format.
type: string
code-coverage-html:
default: ""
description: |
Path to write the code coverage results in HTML format.
type: string
logging-level:
default: ""
description: |
Maximum verbosity level for logged diagnostics included for the test run, specified as `none`, `terse`, `concise`, `detailed`, or `verbose`. By default, the command includes diagnostics logged at the `terse` level.
type: string
model-coverage-cobertura:
default: ""
description: |
Path to write the model coverage results in Cobertura XML format. This parameter requires a Simulink Coverage license and is supported in MATLAB R2018b and later.
type: string
model-coverage-html:
default: ""
description: |
Path to write the model coverage results in HTML format. This parameter requires a Simulink Coverage license and is supported in MATLAB R2018b and later.
type: string
no-output-timeout:
default: 10m
description: |
Elapsed time the tests can run without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”. The default is 10 minutes and the maximum is governed by the maximum time a job is allowed to run.
type: string
output-detail:
default: ""
description: |
Amount of event detail displayed for the test run, specified as `none`, `terse`, `concise`, `detailed`, or `verbose`. By default, the command displays failing and logged events at the `detailed` level and test run progress at the `concise` level.
type: string
select-by-folder:
default: ""
description: |
Location of the folder used to select test suite elements, relative to the project root folder. To create a test suite, MATLAB uses only the tests in the specified folder and its subfolders. You can specify multiple folders using a colon-separated or semicolon-separated list.
type: string
select-by-tag:
default: ""
description: |
Test tag used to select test suite elements. To create a test suite, MATLAB uses only the test elements with the specified tag.
type: string
source-folder:
default: ""
description: |
Location of the folder containing source code, relative to the project root folder. The specified folder and its subfolders are added to the top of the MATLAB search path. If you specify `source-folder` and then generate a coverage report, MATLAB uses only the source code in the specified folder and its subfolders to generate the report. You can specify multiple folders using a colon-separated or semicolon-separated list.
type: string
startup-options:
default: ""
description: |
MATLAB startup options, specified as a list of options separated by spaces. For more information about startup options, see https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html.
type: string
strict:
default: false
description: |
Option to apply strict checks when running tests, specified as `false` or `true`. If you specify a value of `true`, the command generates a qualification failure whenever a test issues a warning.
type: boolean
test-results-html:
default: ""
description: |
Path to write the test results in HTML format.
type: string
test-results-junit:
default: ""
description: |
Path to write the test results in JUnit-style XML format.
type: string
test-results-pdf:
default: ""
description: |
Path to write the test results in PDF format. On macOS platforms, this parameter is supported in MATLAB R2020b and later.
type: string
test-results-simulink-test:
default: ""
description: |
Path to export Simulink Test Manager results in MLDATX format. This parameter requires a Simulink Test license and is supported in MATLAB R2019a and later.
type: string
use-parallel:
default: false
description: |
Option to run tests in parallel, specified as `false` or `true`. If the test runner configuration is suited for parallelization, you can specify a value of `true` to run tests in parallel. This parameter requires a Parallel Computing Toolbox license.
type: boolean
steps:
- run:
command: "#!/bin/bash\n\n# Exit script if you try to use an uninitialized variable.\nset -o nounset\n\n# Exit script if a statement returns a non-true return value.\nset -o errexit\n\n# Use the error status of the first failure, rather than that of the last item in a pipeline.\nset -o pipefail\n\nsudoIfAvailable() {\n if command -v sudo >/dev/null 2>&1; then\n sudo -E bash \"$@\"\n else\n bash \"$@\"\n fi\n}\n\nstream() {\n local url=\"$1\"\n local status=0\n\n if command -v wget >/dev/null 2>&1; then\n wget --retry-connrefused --waitretry=5 -qO- \"$url\" || status=$?\n elif command -v curl >/dev/null 2>&1; then\n curl --retry 5 --retry-connrefused --retry-delay 5 -sSL \"$url\" || status=$?\n else\n echo \"Could not find wget or curl command\" >&2\n return 1\n fi\n\n if [ $status -ne 0 ]; then\n echo \"Error streaming file from $url\" >&2\n fi\n\n return $status\n}\n\ndownload() {\n local url=\"$1\"\n local filename=\"$2\"\n local status=0\n \n if command -v wget >/dev/null 2>&1; then\n wget --retry-connrefused --waitretry=5 -qO \"$filename\" \"$url\" 2>&1 || status=$?\n elif command -v curl >/dev/null 2>&1; then\n curl --retry 5 --retry-all-errors --retry-delay 5 -sSLo \"$filename\" \"$url\" || status=$?\n else\n echo \"Could not find wget or curl command\" >&2\n return 1\n fi\n\n if [ $status -ne 0 ]; then\n echo \"Error downloading file from $url to $filename\" >&2\n fi\n \n return $status\n}\n\ntmpdir=$(mktemp -d 2>/dev/null || mktemp -d -t 'run-tests')\n\n# install run-matlab-command\nstream https://ssd.mathworks.com/supportfiles/ci/run-matlab-command/v2/install.sh | sudoIfAvailable -s -- \"${tmpdir}/bin\"\n\n# download script generator\ndownload https://ssd.mathworks.com/supportfiles/ci/matlab-script-generator/v0/matlab-script-generator.zip \"${tmpdir}/scriptgen.zip\"\nunzip -qod \"${tmpdir}/scriptgen\" \"${tmpdir}/scriptgen.zip\"\n\n# form OS appropriate paths for MATLAB\nos=$(uname)\ngendir=\"$tmpdir\"\nbinext=\"\"\nif [[ \"$os\" = CYGWIN* || \"$os\" = MINGW* || \"$os\" = MSYS* ]]; then\n gendir=$(cygpath -w \"$gendir\")\n binext=\".exe\"\nfi\n\n\"${tmpdir}/bin/run-matlab-command$binext\" \"\\\n addpath('${gendir}/scriptgen');\\\n testScript = genscript('Test',\\\n 'JUnitTestResults','${PARAM_TEST_RESULTS_JUNIT}',\\\n 'CoberturaCodeCoverage','${PARAM_CODE_COVERAGE_COBERTURA}',\\\n 'HTMLCodeCoverage','${PARAM_CODE_COVERAGE_HTML}',\\\n 'SourceFolder','${PARAM_SOURCE_FOLDER}',\\\n 'SelectByFolder','${PARAM_SELECT_BY_FOLDER}',\\\n 'SelectByTag','$PARAM_SELECT_BY_TAG',\\\n 'CoberturaModelCoverage','${PARAM_MODEL_COVERAGE_COBERTURA}',\\\n 'HTMLModelCoverage','${PARAM_MODEL_COVERAGE_HTML}',\\\n 'SimulinkTestResults','${PARAM_TEST_RESULTS_SIMULINK_TEST}',\\\n 'HTMLTestReport','${PARAM_TEST_RESULTS_HTML}',\\\n 'PDFTestReport','${PARAM_TEST_RESULTS_PDF}',\\\n 'Strict',${PARAM_STRICT},\\\n 'UseParallel',${PARAM_USE_PARALLEL},\\\n 'OutputDetail','${PARAM_OUTPUT_DETAIL}',\\\n 'LoggingLevel','${PARAM_LOGGING_LEVEL}');\\\n disp('Running MATLAB script with contents:');\\\n disp(testScript.Contents);\\\n fprintf('__________\\n\\n');\\\n run(testScript);\" $PARAM_STARTUP_OPTIONS\n"
environment:
PARAM_CODE_COVERAGE_COBERTURA: <<parameters.code-coverage-cobertura>>
PARAM_CODE_COVERAGE_HTML: <<parameters.code-coverage-html>>
PARAM_LOGGING_LEVEL: <<parameters.logging-level>>
PARAM_MODEL_COVERAGE_COBERTURA: <<parameters.model-coverage-cobertura>>
PARAM_MODEL_COVERAGE_HTML: <<parameters.model-coverage-html>>
PARAM_OUTPUT_DETAIL: <<parameters.output-detail>>
PARAM_SELECT_BY_FOLDER: <<parameters.select-by-folder>>
PARAM_SELECT_BY_TAG: <<parameters.select-by-tag>>
PARAM_SOURCE_FOLDER: <<parameters.source-folder>>
PARAM_STARTUP_OPTIONS: <<parameters.startup-options>>
PARAM_STRICT: <<parameters.strict>>
PARAM_TEST_RESULTS_HTML: <<parameters.test-results-html>>
PARAM_TEST_RESULTS_JUNIT: <<parameters.test-results-junit>>
PARAM_TEST_RESULTS_PDF: <<parameters.test-results-pdf>>
PARAM_TEST_RESULTS_SIMULINK_TEST: <<parameters.test-results-simulink-test>>
PARAM_USE_PARALLEL: <<parameters.use-parallel>>
name: Run MATLAB tests
no_output_timeout: <<parameters.no-output-timeout>>
shell: bash
examples:
run-build:
description: |
Run a build using the MATLAB build tool.
usage:
version: "2.1"
orbs:
matlab: mathworks/matlab@1
jobs:
build:
machine:
image: ubuntu-2204:2024.01.1
steps:
- checkout
- matlab/install
- matlab/run-build:
tasks: test
workflows:
build:
jobs:
- build
run-custom-script:
description: |
Run a MATLAB script in your project.
usage:
version: "2.1"
orbs:
matlab: mathworks/matlab@1
jobs:
build:
machine:
image: ubuntu-2204:2024.01.1
steps:
- checkout
- matlab/install
- matlab/run-command:
command: myscript
workflows:
build:
jobs:
- build
run-tests-with-report:
description: |
Run all tests in your project and produce test results in JUnit-style XML format.
usage:
version: "2.1"
orbs:
matlab: mathworks/matlab@1
jobs:
build:
machine:
image: ubuntu-2204:2024.01.1
steps:
- checkout
- matlab/install:
products: Simulink Simulink_Test
- matlab/run-tests:
test-results-junit: test-results/matlab/results.xml
- store_test_results:
path: test-results
workflows:
build:
jobs:
- build