Tips for Setting Up CI Agents

This example uses:

CI Support Package for Simulink CI Support Package for Simulink

A build agent is a machine that is responsible for running MATLAB^® and communicating the results back to your chosen CI platform. Depending on the CI platform, you might set up the platform to run MATLAB on your own, self-hosted machine or in the cloud. Use the following suggestions to help set up your build agent.

For information on how to create a Docker^® container for the support package, see Build and Use Docker Image to Run Processes.

Product Installation

To use the support package in CI, you must install at least these products on your build agent:

MATLAB
Simulink^®
Simulink Check™
CI Support Package for Simulink

You must also install any other products required by your process. For example, the default process model also uses:

Embedded Coder^®
MATLAB Coder™
MATLAB Report Generator™
Polyspace^® Bug Finder™
Polyspace Code Prover™
Requirements Toolbox™
Simulink Coder
Simulink Coverage™
Simulink Design Verifier™
Simulink Report Generator
Simulink Test™

You can programmatically install products by using the MATLAB Package Manager (MPM).

Note

License Considerations for CI: If you plan to perform CI on many hosts or in the cloud, transformational products such as MathWorks^® coder and compiler products might require client access licenses (CAL). If you encounter a product licensing issue, consider requesting a MATLAB batch licensing token to use in your pipeline. For more information, see Use MATLAB Batch Licensing Token.

Set Up Virtual Display Machines Without Displays

Some MATLAB code, including some built-in tasks, can only run successfully if a display is available for your machine. When there is no display available, MATLAB returns an error.

A machine might not have a display available if either:

You start MATLAB using the -nodisplay option.
The machine does not have a display configured and the DISPLAY environment variable is not set. For example:
- some CI runners
- some containers, including Docker containers by default
- machines that you SSH into without X11 forwarding

If MATLAB returns an error related to your display, try the following workaround. You can set up a virtual display on the machine to simulate a display environment. The virtual display allows you to run MATLAB code that requires a display, without having to connect your machine to a physical display.

Choose a server. There are several common servers that you can install and use to host your virtual display, including:
- Xvfb
- VNC server
Install the server on the machine. For example, to install Xvfb on a Linux^® machine:
```
sudo apt-get install xvfb
```
Alternatively, for a containerized environment, you can instruct your container image to install and use the server as the display. For example, to install and use Xvfb for a Docker container, your Dockerfile can include:
```
RUN apt-get install --no-install-recommends --yes xvfb
RUN export DISPLAY=:`Xvfb -displayfd 1 &` && \
```
To access an example Dockerfile that uses Xvfb, enter the following command in MATLAB:
```
cd(fullfile(matlabshared.supportpkg.getSupportPackageRoot,...
"toolbox","padv","samples"))
```
Run MATLAB in the server environment.
For example, with Xvfb on a Linux machine, you can use the xvfb-run command to run your MATLAB code with a virtual display. For example:
```
xvfb-run matlab -batch "openProject(projectPath);runprocess;"
```
For information, see xvfb-run.

Note

Depending on which server you choose, you might must manually start the server and set the DISPLAY environment variable on your machine to use your virtual display. The DISPLAY environment variable cannot be left empty.

Since most CI runners and containers do not have a display available, you should set up a virtual display server before you include the following built-in tasks in your process model:

Platform Limitations

On Windows^®, the maximum path length of 260 characters can cause "Path too long" errors when cloning repositories and running CI builds. To reduce the length of file paths, specify locations that are closer to the root of the drive or enable long paths. Typically, you can resolve most path length issues by enabling the long paths feature in Windows as shown in the Microsoft^® documentation Registry setting to enable long paths. For more information, see the Microsoft documentation for Maximum Path Length Limitation.

Dry Run Your Process

Before you try to run your process on your build agent, you can dry run your process. The dry run can validate your task inputs, generate representative task outputs, and make sure that you have the required licenses available on your build agent.

To perform a dry run, you can use the DryRun argument of the runprocess function. For example:

runprocess(DryRun = true)

To automatically check out the licenses associated with the tasks, you can specify the DryRunLicenseCheckout argument as true:

runprocess(DryRun = true, DryRunLicenseCheckout = true)

Dry runs can be helpful for quickly testing out your CI pipeline and making sure that your required products and licenses are available, locally and on your build agents. The built-in tasks have a dryRun method that generates representative task outputs for that task. You can define your own custom dry run functionality by overriding the dryRun method for class-based tasks or specifying the task property DryRunAction for function-based tasks.

For more information on dry runs, see Dry Run Tasks to Test Process Model.