Use MATLAB with CircleCI

The orb for MATLAB® on the CircleCI® Orb Registry enables you to build and test your MATLAB project as part of your pipeline. For example, you can automatically identify any code issues in your project, run tests and generate test and coverage artifacts, and package your files into a toolbox.

To use this orb, opt in to using third-party orbs in your organization security settings. You can run MATLAB on a cloud-hosted runner (executor) by invoking the orb in your CircleCI configuration file and authoring your pipeline using the orb commands as steps in jobs. You must include the install command in your jobs to install your preferred MATLAB release on the runner. For more information about cloud-hosted runners, see Execution environments overview.

Examples

When you author your pipeline in a file named .circleci/config.yml in the root of your repository, the orb provides you with four commands:

• install command — Install a specific release of MATLAB on a cloud-hosted runner.
• run-build command — Run a MATLAB build using the MATLAB build tool.
• run-tests command — Run MATLAB and Simulink® tests and generate artifacts.
• run-command command — Run MATLAB scripts, functions, and statements.

Run a MATLAB Build

Using the latest release of MATLAB, run a MATLAB build task named mytask and each task it depends on. These tasks must be specified in a build file named buildfile.m in the root of your repository. To install the latest release of MATLAB on the runner, specify the install command in your pipeline. To run the MATLAB build task mytask, specify the tasks parameter of the run-build command. (The run-build command is supported in MATLAB R2022b and later.)

version: 2.1
orbs:
  matlab: mathworks/matlab@1
jobs:
  run-matlab-build:    
    machine:
      image: ubuntu-2204:current
    steps:
      - checkout
      - matlab/install
      - matlab/run-build:
          tasks: mytask
workflows:
  build:
    jobs:
      - run-matlab-build

Generate Test and Coverage Artifacts

Using the latest release of MATLAB, run the tests in your MATLAB project and generate test results in PDF and JUnit-style XML formats and code coverage results in HTML format. Upload the generated artifacts to CircleCI once the test run is complete. To install the latest release of MATLAB on the runner, specify the install command in your pipeline. To run the tests and generate the artifacts, specify the run-tests command.

version: 2.1
orbs:
  matlab: mathworks/matlab@1
jobs:
  run-matlab-tests:    
    machine:
      image: ubuntu-2204:current
    steps:
      - checkout
      - matlab/install
      - matlab/run-tests:
          test-results-pdf: test-results/results.pdf
          test-results-junit: test-results/results.xml
          code-coverage-html: code-coverage
      - store_artifacts:
          path: test-results/results.pdf
      - store_test_results:
          path: test-results/results.xml
      - store_artifacts:
          path: code-coverage
workflows:
  test:
    jobs:
      - run-matlab-tests  

You can access the artifacts on the pipeline's Job page in the CircleCI web app:

• To view the test results in JUnit-style XML format, open the Tests tab.
• To access the PDF test report and HTML code coverage report, open the Artifacts tab.

Run Tests in Parallel

Run your MATLAB and Simulink tests in parallel (requires Parallel Computing Toolbox™) using the latest release of the required products. To install the latest release of MATLAB, Simulink, Simulink Test™, and Parallel Computing Toolbox on the runner, specify the products parameter of the install command in your pipeline. To run the tests in parallel, specify the use-parallel parameter of the run-tests command.

version: 2.1
orbs:
  matlab: mathworks/matlab@1
jobs:
  run-matlab-and-simulink-tests:    
    machine:
      image: ubuntu-2204:current
    steps:
      - checkout
      - matlab/install:
          products: >
            Simulink 
            Simulink_Test 
            Parallel_Computing_Toolbox
      - matlab/run-tests:
          use-parallel: true
workflows:
  test:
    jobs:
      - run-matlab-and-simulink-tests

Run MATLAB Script

Run the commands in a file named myscript.m in the root of your repository using MATLAB R2023b. To install the specified release of MATLAB on the runner, specify the release parameter of the install command in your pipeline. To run the script, specify the run-command command.

version: 2.1
orbs:
  matlab: mathworks/matlab@1
jobs:
  run-matlab-script:    
    machine:
      image: ubuntu-2204:current
    steps:
      - checkout
      - matlab/install:
          release: R2023b
      - matlab/run-command:
          command: myscript
workflows:
  build:
    jobs:
      - run-matlab-script

Use MATLAB Batch Licensing Token

You need a MATLAB batch licensing token if your project is private or if your pipeline includes transformation products, such as MATLAB Coder™ and MATLAB Compiler™. Batch licensing tokens are strings that enable MATLAB to start in noninteractive environments. You can request a token by submitting the MATLAB Batch Licensing Pilot form.

To use a MATLAB batch licensing token:

1. Create a context and add an environment variable with MLM_LICENSE_TOKEN as its name and the batch licensing token as its value. For more information about contexts, see Using contexts.
2. Using the context in the workflows section of your pipeline, give jobs that include the run-build, run-tests, and run-command commands access to the MLM_LICENSE_TOKEN environment variable.

For example, use the latest release of MATLAB to run the tests in your private project. To install the latest release of MATLAB on the runner, specify the install command in your pipeline. To run the tests, specify the run-tests command. In this example, my-context is the name of the context that includes the MLM_LICENSE_TOKEN environment variable.

version: 2.1
orbs:
  matlab: mathworks/matlab@1
jobs:
  run-matlab-tests:
    machine:
      image: ubuntu-2204:current
    steps:
      - checkout
      - matlab/install
      - matlab/run-tests
workflows:
  test:
    jobs:
      - run-matlab-tests:
          context: my-context

Build Across Multiple Platforms

The install command supports the Linux®, Windows®, and macOS platforms. Use a matrix job to run a build using the MATLAB build tool on all the supported platforms. This pipeline runs the specified job three times.

version: 2.1
orbs:
  matlab: mathworks/matlab@1

executors:
  linux:
    machine:
      image: ubuntu-2204:current
  windows:
    resource_class: windows.medium
    machine:
      image: windows-server-2022-gui:current
  macos:
    macos:
      xcode: 14.2.0

jobs:
  run-matlab-build:
    parameters:
      os:
        type: executor
    executor: << parameters.os >>
    steps:
      - checkout
      - matlab/install
      - matlab/run-build:
          tasks: mytask

workflows:
  build:
    jobs:
      - run-matlab-build:
          matrix:
            parameters:
              os: [linux, windows, macos]

Split Tests Across Runners

The run-tests command is compatible with CircleCI test splitting, which enables you to split your tests by name, file size, or timing data, and run them across parallel execution environments. To split your MATLAB tests across runners:

1. Specify the number of runners across which to split your tests by using the parallelism key.
2. Specify the select-by-name parameter of the run-tests command using one of the options provided by the CircleCI CLI. For more information about the CLI, see Use the CircleCI CLI to split tests.

For example, suppose that your MATLAB test files are located in a folder named tests in the root of your repository as well as in its subfolders. In other words, suppose that the glob pattern "tests/**/*.m" represents all your test files. Split the tests by name and run them across four runners.

version: 2.1
orbs:
  matlab: mathworks/matlab@1
jobs:
  run-matlab-tests:    
    machine:
      image: ubuntu-2204:current
    parallelism: 4
    steps:
      - checkout
      - matlab/install
      - matlab/run-tests:
          select-by-name: $(circleci tests glob "tests/**/*.m" | circleci tests split | awk -F'[\\\\/.]' '{print $(NF-1) "/*"}')
workflows:
  test:
    jobs:
      - run-matlab-tests

To split the tests specified by the "tests/**/*.m" glob pattern using file size, you can specify select-by-name like this:

select-by-name: $(circleci tests glob "tests/**/*.m" | circleci tests split --split-by=filesize | awk -F'[\\\\/.]' '{print $(NF-1) "/*"}')

Timing-based test splitting relies on timing data collected from a previous test run. To use this strategy, you must produce test results in JUnit-style XML format (by specifying the test-results-junit parameter of the run-tests command) so that CircleCI can access the historic timing data from the test results. To split the tests specified by the "tests/**/*.m" glob pattern using timing data, you can specify select-by-name like this:

select-by-name: $(circleci tests glob "tests/**/*.m" | awk -F'[\\\\/.]' '{print $(NF-1)}' | circleci tests split --split-by=timings | awk '{print $0 "/*"}')

Commands

You can access the orb commands in the CircleCI configuration editor.

install

Use the install command to install MATLAB and other MathWorks® products on a cloud-hosted runner. When you specify this command as part of your pipeline, the command installs your preferred MATLAB release (R2021a or later) on a Linux, Windows, or macOS runner and prepends it to the PATH system environment variable. If you do not specify a release, the command installs the latest release of MATLAB.

The install command accepts optional parameters.

Parameter	Description
release	(Optional) MATLAB release to install. You can specify R2021a or a later release. By default, the value of release is latest, which corresponds to the latest release of MATLAB. To install the latest update of a release, specify only the release name, for example, R2023b. To install a specific update release, specify the release name with an update number suffix, for example, R2023bU4. To install a release without updates, specify the release name with an update 0 or general release suffix, for example, R2023bU0 or R2023bGR. Example: release: R2023b Example: release: latest Example: release: R2023bU4
products	(Optional) Products to install in addition to MATLAB, specified as a list of product names separated by spaces. You can specify products to install most MathWorks products and support packages. The command uses MATLAB Package Manager (mpm) to install products. For a list of supported products, open the input file for your preferred release from the mpm-input-files folder on GitHub®. Specify products using the format shown in the input file, excluding the #product. prefix. For example, to install Deep Learning Toolbox™ in addition to MATLAB, specify products: Deep_Learning_Toolbox. For an example of how to use the products parameter, see Run Tests in Parallel. Example: products: Simulink Example: products: Simulink Deep_Learning_Toolbox
no-output-timeout	(Optional) Amount of time the command can run without producing output, specified as a numeric value suffixed with a time unit. By default, the no-output timeout is 10 minutes (10m). The maximum value is governed by the maximum time a job is allowed to run. Example: no-output-timeout: 30s Example: no-output-timeout: 5m Example: no-output-timeout: 0.5h

Licensing

Product licensing for your pipeline depends on your project visibility as well as the type of products to install:

• Public project — If your pipeline does not include transformation products, such as MATLAB Coder and MATLAB Compiler, then the orb automatically licenses any products that you install. If your pipeline includes transformation products, you can request a MATLAB batch licensing token by submitting the MATLAB Batch Licensing Pilot form.
• Private project — The orb does not automatically license any products for you. You can request a token by submitting the MATLAB Batch Licensing Pilot form.

To use a MATLAB batch licensing token, first store the token in a context environment variable named MLM_LICENSE_TOKEN. Then, using the context in the workflows section of your pipeline, give jobs that include the run-build, run-tests, and run-command commands access to the environment variable. For an example, see Use MATLAB Batch Licensing Token.

Note: The install command automatically includes the MATLAB batch licensing executable (matlab-batch). To use a MATLAB batch licensing token in a pipeline that does not use this command, you must first download the executable and add it to the system path.

run-build

Use the run-build command to run a build using the MATLAB build tool. Starting in R2022b, you can use this command to run the MATLAB build tasks specified in a build file. By default, the run-build command looks for a build file named buildfile.m in the root of your repository. For more information about the build tool, see Overview of MATLAB Build Tool.

The run-build command accepts optional parameters.

Parameter	Description
tasks	(Optional) MATLAB build 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 your build file 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. Example: tasks: test Example: tasks: compile test Example: tasks: check test("myFolder",OutputDetail="concise") archive("source.zip")
build-options	(Optional) 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 function. Example: build-options: -continueOnFailure Example: build-options: -continueOnFailure -skip test
startup-options	(Optional) MATLAB startup options, specified as a list of options separated by spaces. For more information about startup options, see Commonly Used Startup Options. Using this parameter to specify the -batch or -r option is not supported. Example: startup-options: -nojvm Example: startup-options: -nojvm -logfile output.log
no-output-timeout	(Optional) Amount of time the command can run without producing output, specified as a numeric value suffixed with a time unit. By default, the no-output timeout is 10 minutes (10m). The maximum value is governed by the maximum time a job is allowed to run. Example: no-output-timeout: 30s Example: no-output-timeout: 5m Example: no-output-timeout: 0.5h

run-tests

Use the run-tests command to run tests authored using the MATLAB unit testing framework or Simulink Test and generate test and coverage 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.

The run-tests command accepts optional parameters.

Parameter	Description
source-folder	(Optional) Location of the folder containing source code, specified as a path 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, the command 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. Example: source-folder: source Example: source-folder: source/folderA; source/folderB
select-by-folder	(Optional) Location of the folder containing the tests to run, specified as a path relative to the project root folder. If you specify this parameter, the command runs only the tests in the specified folder and its subfolders. You can specify multiple folders using a colon-separated or semicolon-separated list. Example: select-by-folder: test Example: select-by-folder: test/folderA; test/folderB
select-by-name	(Optional) Names of the tests to run, specified as a list of test names separated by spaces. If you specify this parameter, the command runs only the tests with the specified names. You can use the wildcard character (*) to match any number of characters and the question mark character (?) to match a single character. For example, specify select-by-name: ExampleTest/* to select all the tests whose name starts with ExampleTest/. For a given test file, the name of a test uniquely identifies the smallest runnable portion of the test content. The test name includes the namespace name, filename (excluding the extension), procedure name, and information about parameterization. Example: select-by-name: ExampleTest/testA Example: select-by-name: ExampleTest/testA ExampleTest/testB(array=3x3_double)
select-by-tag	(Optional) Tag of the tests to run, specified as a string scalar. If you specify this parameter, the command runs only the tests with the specified tag. For more information about test tags, see Tag Unit Tests. Example: select-by-tag: Unit
strict	(Optional) Option to apply strict checks when running tests, specified as false or true. By default, the value is false. If you specify a value of true, the command generates a qualification failure whenever a test issues a warning. Example: strict: true
use-parallel	(Optional) Option to run tests in parallel, specified as false or true. By default, the value is false and tests run in serial. 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. Example: use-parallel: true
output-detail	(Optional) 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. Example: output-detail: verbose
logging-level	(Optional) 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. Example: logging-level: detailed
test-results-html	(Optional) Location to write the test results in HTML format, specified as a folder path relative to the project root folder. Example: test-results-html: test-results
test-results-pdf	(Optional) Location to write the test results in PDF format, specified as a file path relative to the project root folder. On macOS platforms, this parameter is supported in MATLAB R2020b and later. Example: test-results-pdf: test-results/results.pdf
test-results-junit	(Optional) Location to write the test results in JUnit-style XML format, specified as a file path relative to the project root folder. Example: test-results-junit: test-results/results.xml
test-results-simulink-test	(Optional) Location to export Simulink Test Manager results in MLDATX format, specified as a file path relative to the project root folder. This parameter requires a Simulink Test license and is supported in MATLAB R2019a and later. Example: test-results-simulink-test: test-results/results.mldatx
code-coverage-html	(Optional) Location to write the code coverage results in HTML format, specified as a folder path relative to the project root folder. Example: code-coverage-html: code-coverage
code-coverage-cobertura	(Optional) Location to write the code coverage results in Cobertura XML format, specified as a file path relative to the project root folder. Example: code-coverage-cobertura: code-coverage/coverage.xml
model-coverage-html	(Optional) Location to write the model coverage results in HTML format, specified as a folder path relative to the project root folder. This parameter requires a Simulink Coverage™ license and is supported in MATLAB R2018b and later. Example: model-coverage-html: model-coverage
model-coverage-cobertura	(Optional) Location to write the model coverage results in Cobertura XML format, specified as a file path relative to the project root folder. This parameter requires a Simulink Coverage license and is supported in MATLAB R2018b and later. Example: model-coverage-cobertura: model-coverage/coverage.xml
startup-options	(Optional) MATLAB startup options, specified as a list of options separated by spaces. For more information about startup options, see Commonly Used Startup Options. Using this parameter to specify the -batch or -r option is not supported. Example: startup-options: -nojvm Example: startup-options: -nojvm -logfile output.log
no-output-timeout	(Optional) Amount of time the command can run without producing output, specified as a numeric value suffixed with a time unit. By default, the no-output timeout is 10 minutes (10m). The maximum value is governed by the maximum time a job is allowed to run. Example: no-output-timeout: 30s Example: no-output-timeout: 5m Example: no-output-timeout: 0.5h

Note: To customize the pretest state of the system, you can specify startup code that automatically executes before your tests run. For information on how to specify startup or shutdown files in a MATLAB project, see Automate Startup and Shutdown Tasks. If your pipeline does not use a MATLAB project, specify the commands you want executed at startup in a startup.m file instead, and save the file to the root of your repository. See startup for more information.

run-command

Use the run-command command to run MATLAB scripts, functions, and statements. You can use this command to flexibly customize your test run or add a step in MATLAB to your pipeline.

The run-command command requires a parameter and also accepts optional parameters.

Parameter	Description
command	(Required) 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 orb command to fail. To fail the orb command in certain conditions, use the assert or error function. Example: command: myscript Example: command: results = runtests, assertSuccess(results);
startup-options	(Optional) MATLAB startup options, specified as a list of options separated by spaces. For more information about startup options, see Commonly Used Startup Options. Using this parameter to specify the -batch or -r option is not supported. Example: startup-options: -nojvm Example: startup-options: -nojvm -logfile output.log
no-output-timeout	(Optional) Amount of time the command can run without producing output, specified as a numeric value suffixed with a time unit. By default, the no-output timeout is 10 minutes (10m). The maximum value is governed by the maximum time a job is allowed to run. Example: no-output-timeout: 30s Example: no-output-timeout: 5m Example: no-output-timeout: 0.5h

When you use this orb command, all of the required files must be on the MATLAB search path. If your script or function is not in the root of your repository, you can use the addpath, cd, or run function to put it on the path. For example, to run myscript.m in a folder named myfolder located in the root of the repository, you can specify command like this:

command: addpath("myfolder"), myscript

Notes

• By default, when you use the run-build, run-tests, or run-command command, the root of your repository serves as the MATLAB startup folder. To run your MATLAB code using a different folder, specify the -sd startup option or include the cd command when using run-command.
• The run-build command uses the -batch option to invoke the MATLAB build tool. In addition, in MATLAB R2019a and later, the run-tests and run-command commands use the -batch option to start MATLAB noninteractively. Preferences do not persist across different MATLAB sessions launched with the -batch option. To run code that requires the same preferences, use a single command.
• When you use the install, run-build, run-tests, and run-command commands, you execute third-party code that is licensed under separate terms.

See Also

• Continuous Integration with MATLAB and Simulink
• Continuous Integration with MATLAB on CI Platforms

Contact Us

If you have any questions or suggestions, contact MathWorks at [email protected].