└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Use MATLAB with GitLab CI/CD 2 | You can use [GitLab™ CI/CD](https://docs.gitlab.com/ee/ci/index.html) to build and test your MATLAB® project as part of your pipeline. For example, you can identify code issues in your project, run your tests and generate test and coverage artifacts, and package your files into a toolbox. 3 | 4 | The `MATLAB.gitlab-ci.yml` [template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/MATLAB.gitlab-ci.yml) provides you with jobs that show how to run MATLAB statements, tests, and builds. To run MATLAB code and Simulink® models based on this template, you must use the Docker® executor to run MATLAB within a container. You can use the [MATLAB Container on Docker Hub](https://www.mathworks.com/help/cloudcenter/ug/matlab-container-on-docker-hub.html) to run your build using MATLAB R2020b or a later release. Alternatively, you can create your own container for MATLAB and other MathWorks® products. For more information on how to create and use a custom MATLAB container, see [Create a MATLAB Container Image for Non-Interactive Workflows](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/alternates/non-interactive/README.md). 5 | 6 | >**Note:** In addition to the Docker executor, GitLab Runner implements other types of executors that can be used to run your builds. See [Executors](https://docs.gitlab.com/runner/executors/) for more information. 7 | 8 | ## MATLAB.gitlab-ci.yml Template 9 | You can access the `MATLAB.gitlab-ci.yml` template when you create a `.gitlab-ci.yml` file in the UI. 10 | 11 | ![template](https://user-images.githubusercontent.com/48831250/166474348-2e106005-23eb-4d62-a0ba-3387bbfcb20a.png) 12 | 13 | The template includes four jobs: 14 | 15 | * `command` — Run MATLAB scripts, functions, and statements. 16 | * `test` — Run tests authored using the MATLAB unit testing framework or Simulink Test™. 17 | * `test_artifacts` — Run MATLAB and Simulink tests, and generate test and coverage artifacts. 18 | * `build` — Run a build using the MATLAB build tool. 19 | 20 | The jobs in the template use the `matlab -batch` syntax to start MATLAB. Additionally, they incorporate the contents of a hidden `.matlab_defaults` job. You need to configure this job before running the `command`, `test`, `test_artifacts`, and `build` jobs. To configure the job: 21 | 22 | * Specify the name of the MATLAB container image you want to use. 23 | * Set the `MLM_LICENSE_FILE` environment variable using the port number and DNS address for your network license manager. 24 | 25 | ```yaml 26 | .matlab_defaults: 27 | image: 28 | name: mathworks/matlab:latest # Replace the value with the name of the MATLAB container image you want to use 29 | entrypoint: [""] 30 | variables: 31 | MLM_LICENSE_FILE: 27000@MyLicenseServer # Replace the value with the port number and DNS address for your network license manager 32 | 33 | ``` 34 | 35 | ## Examples 36 | Each of these examples shows how to specify the contents of a job in your `.gitlab-ci.yml` file. 37 | 38 | ### Run a Script 39 | Run the commands in a file named `myscript.m` in the root of your repository. 40 | 41 | ```yaml 42 | command: 43 | extends: .matlab_defaults 44 | script: matlab -batch "myscript" 45 | ``` 46 | ### Run Tests 47 | Run the tests in your [MATLAB project](https://www.mathworks.com/help/matlab/projects.html) and fail the build if any of the tests fail. 48 | 49 | ```yaml 50 | test: 51 | extends: .matlab_defaults 52 | script: matlab -batch "results = runtests('IncludeSubfolders',true), assertSuccess(results);" 53 | ``` 54 | ### Run Tests and Generate Artifacts 55 | Run the tests in your MATLAB project, and produce test results in JUnit-style XML format and code coverage results in Cobertura XML format. Fail the build if any of the tests fail. 56 | 57 | ```yaml 58 | test_artifacts: 59 | extends: .matlab_defaults 60 | script: | 61 | cat <<- 'BLOCK' > runAllTests.m 62 | import matlab.unittest.TestRunner 63 | import matlab.unittest.Verbosity 64 | import matlab.unittest.plugins.CodeCoveragePlugin 65 | import matlab.unittest.plugins.XMLPlugin 66 | import matlab.unittest.plugins.codecoverage.CoberturaFormat 67 | suite = testsuite(pwd,'IncludeSubfolders',true); 68 | [~,~] = mkdir('artifacts') 69 | runner = TestRunner.withTextOutput('OutputDetail',Verbosity.Detailed); 70 | runner.addPlugin(XMLPlugin.producingJUnitFormat('artifacts/results.xml')) 71 | % Replace `pwd` with the location of the folder containing source code 72 | runner.addPlugin(CodeCoveragePlugin.forFolder(pwd,'IncludingSubfolders',true, ... 73 | 'Producing',CoberturaFormat('artifacts/cobertura.xml'))) 74 | results = runner.run(suite) 75 | assertSuccess(results); 76 | BLOCK 77 | matlab -batch runAllTests 78 | artifacts: 79 | reports: 80 | junit: "./artifacts/results.xml" 81 | coverage_report: 82 | coverage_format: cobertura 83 | path: "./artifacts/cobertura.xml" 84 | paths: 85 | - "./artifacts" 86 | ``` 87 | 88 | ### Run MATLAB Build 89 | Use the [MATLAB build tool](https://www.mathworks.com/help/matlab/matlab_prog/overview-of-matlab-build-tool.html) to run the default tasks in a file named `buildfile.m` located in the root of your repository, as well as all the tasks on which they depend. 90 | 91 | ```yaml 92 | build: 93 | extends: .matlab_defaults 94 | script: matlab -batch "buildtool" 95 | ``` 96 | 97 | ## See Also 98 | - [Continuous Integration with MATLAB and Simulink](https://www.mathworks.com/solutions/continuous-integration.html) 99 | - [Continuous Integration for Verification of Simulink Models Using GitLab](https://www.mathworks.com/company/newsletters/articles/continuous-integration-for-verification-of-simulink-models-using-gitlab.html) 100 | 101 | ## Contact Us 102 | If you have any questions or suggestions, please contact MathWorks® at [continuous-integration@mathworks.com](mailto:continuous-integration@mathworks.com). 103 | --------------------------------------------------------------------------------