Tips for Setting Up CI Agents

This example uses:

CI Support Package for Simulink CI Support Package for Simulink

A CI 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 CI agent.

Product Installation

To use the support package in CI, you must install at least these products on your CI 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). For more information, see MATLAB Package Manager.

Note

License Considerations for CI: If you plan to perform CI on many hosts or in the cloud, contact MathWorks^® (continuous-integration@mathworks.com) for help. Transformational products such as MathWorks coder and compiler products might require client access licenses (CAL).

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 CI 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 CI 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 CI 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.

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:

Create Docker Container for Support Package

A container is an isolated unit of software that contains everything required to run a specific application. You can use a container as a scalable and reproducible way to deploy and test your process.

You can follow these steps to create a Docker image that includes MATLAB, other MathWorks products, and the CI Support Package for Simulink. The example Dockerfile installs the support package and other products by using the MATLAB Package Manager (MPM). Since certain MATLAB code requires a display to run successfully, the example Dockerfile uses Xvfb to set up a virtual display for the container.

The MATLAB Docker image is a Linux executable, but can run on any host operating system that Docker supports. For general information about MATLAB container images, see matlab-dockerfile.

Install Docker on your machine. For information, see Get Docker.

To access the example Dockerfile for Process Advisor, open MATLAB and enter:

open(fullfile(matlabshared.supportpkg.getSupportPackageRoot,...
"toolbox","padv","samples","Dockerfile"))

Save a copy of the file, Dockerfile (no file extension), in a directory that your Docker daemon can access.
Build a Docker image by using the docker build command. You can use the build-time variables to specify the MATLAB release, MathWorks products, installation location, network license, and name for your container image. For example:
```
docker build --build-arg MATLAB_RELEASE=2023b 
--build-arg PRODUCTS="MATLAB Simulink Simulink_Check CI/CD_Automation_for_Simulink_Check" 
--build-arg MATLAB_INSTALL_LOCATION="/opt/matlab/R2023b" 
--build-arg LICENSE_SERVER=port@hostname 
-t my_matlab_image_name .
```
This example code only installs the products required by the support package. If you want to be able to run all of the built-in tasks, see the example Dockerfile for a list of the other products to add to the PRODUCTS list.
Use the build-arg LICENSE_SERVER to specify the port and hostname for your network license manager.
Alternatively, you can place your network.lic file in the same folder as the example Dockerfile, uncomment the line COPY network.lic ${MATLAB_INSTALL_LOCATION}/licenses in the example Dockerfile, and run the docker build command without the LICENSE_SERVER build-arg.
```
docker build --build-arg MATLAB_RELEASE=2023b 
--build-arg PRODUCTS="MATLAB Simulink Simulink_Check CI/CD_Automation_for_Simulink_Check" 
--build-arg MATLAB_INSTALL_LOCATION="/opt/matlab/R2023b" 
-t my_matlab_image_name .
```
For more information, see docker buildx build and matlab-dockerfile.

Note
The example Dockerfile assumes that you are using the network license manager to license and run MATLAB. If you run MATLAB using a different licensing approach, contact MathWorks (continuous-integration@mathworks.com) for help.
Create and run a container from the generated image by using the docker run command.
```
docker run --init --rm my_matlab_image_name -batch "ver"
```
For information, see docker container run.