> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# mathworks/matlab

Run MATLAB as part of your build pipeline.


## Commands

### install

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 | Type | Default | Description |
|---|---|---|---|
| `cache` | boolean | false | Option to enable caching, specified as false or true. By default, the value is false and the command does not store MATLAB and the specified products in a cache for future use.
 |
| `no-output-timeout` | string | 10m | 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.
 |
| `products` | string |  | 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.
 |
| `release` | string | latest | 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.
 |

### run-build

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 | Type | Default | Description |
|---|---|---|---|
| `build-options` | string |  | 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-output-timeout` | string | 10m | 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.
 |
| `startup-options` | string |  | 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.
 |
| `tasks` | string |  | 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.
 |

### run-command

Run MATLAB scripts, functions, and statements. When you use this command, all of the required files must be on the MATLAB search path.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `command` | string |  | 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.
 |
| `no-output-timeout` | string | 10m | 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.
 |
| `startup-options` | string |  | 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.
 |

### run-tests

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 | Type | Default | Description |
|---|---|---|---|
| `code-coverage-cobertura` | string |  | Path to write the code coverage results in Cobertura XML format.
 |
| `code-coverage-html` | string |  | Path to write the code coverage results in HTML format.
 |
| `logging-level` | string |  | 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.
 |
| `model-coverage-cobertura` | string |  | 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.
 |
| `model-coverage-html` | string |  | 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-output-timeout` | string | 10m | 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.
 |
| `output-detail` | string |  | 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.
 |
| `select-by-folder` | string |  | 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.
 |
| `select-by-name` | string |  | Name of the test used to select test suite elements, specified as a list of names separated by spaces. The command filters an existing test suite to include only the test elements that match the specified names. Use the wildcard character (*) to match any number of characters. Use the question mark character (?) to match a single character.
 |
| `select-by-tag` | string |  | Test tag used to select test suite elements. To create a test suite, MATLAB uses only the test elements with the specified tag.
 |
| `source-folder` | string |  | 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.
 |
| `startup-options` | string |  | 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.
 |
| `strict` | boolean | false | 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.
 |
| `test-results-html` | string |  | Path to write the test results in HTML format.
 |
| `test-results-junit` | string |  | Path to write the test results in JUnit-style XML format.
 |
| `test-results-pdf` | string |  | Path to write the test results in PDF format. On macOS platforms, this parameter is supported in MATLAB R2020b and later.
 |
| `test-results-simulink-test` | string |  | 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.
 |
| `use-parallel` | boolean | false | 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.
 |

## Examples

### run-build

Run a build using the MATLAB build tool.


```yaml
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

Run a MATLAB script in your project.


```yaml
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

Run all tests in your project and produce test results in JUnit-style XML format.


```yaml
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
```