You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+8-10Lines changed: 8 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,4 @@
1
1
# Action for Running MATLAB Builds
2
-
3
2
Starting in R2022b, the MATLAB® build tool provides a standard programming interface to create and run tasks in a uniform and efficient way. For example, you can create tasks that identify code issues, run tests, and package a toolbox in a single build file in your project root folder, and then invoke the build tool to run these tasks. For more information, see [Overview of MATLAB Build Tool](https://www.mathworks.com/help/matlab/matlab_prog/overview-of-matlab-build-tool.html).
4
3
5
4
The [Run MATLAB Build](#run-matlab-build) action enables you to invoke the MATLAB build tool on a [GitHub®-hosted](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners) or [self-hosted](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) runner:
@@ -8,11 +7,9 @@ The [Run MATLAB Build](#run-matlab-build) action enables you to invoke the MATLA
8
7
- To use a self-hosted runner, set up a computer with MATLAB on its path and register the runner with GitHub Actions. (On self-hosted UNIX® runners, you can also use the **Setup MATLAB** action instead of having MATLAB already installed.) The runner uses the topmost MATLAB release on the system path to execute your workflow.
9
8
10
9
## Examples
11
-
12
10
Use the **Run MATLAB Build** action to run a build using the MATLAB build tool. You can use this action to run the tasks in your build file. (By default, the action looks for a build file named `buildfile.m` in the root of your repository.) To use the **Run MATLAB Build** action, you need MATLAB R2022b or a later release.
13
11
14
12
### Run Default Tasks in Build File
15
-
16
13
On a self-hosted runner that has MATLAB installed, run the default tasks in a build file named `buildfile.m` in the root of your repository as well as all the tasks on which they depend. To run the tasks, specify the **Run MATLAB Build** action in your workflow.
17
14
18
15
```yaml
@@ -30,7 +27,6 @@ jobs:
30
27
```
31
28
32
29
### Run Specified Task in Build File
33
-
34
30
Using the latest release of MATLAB on a GitHub-hosted runner, run a task named `mytask`, specified in a build file named `buildfile.m` in the root of your repository, as well as all the tasks on which it depends. To set up the latest release of MATLAB on the runner, specify the [Setup MATLAB](https://github.com/matlab-actions/setup-matlab/) action in your workflow. To run the MATLAB build, specify the **Run MATLAB Build** action.
35
31
36
32
```yaml
@@ -52,7 +48,6 @@ jobs:
52
48
```
53
49
54
50
### Use MATLAB Batch Licensing Token
55
-
56
51
When you define a workflow using the [Setup MATLAB](https://github.com/matlab-actions/setup-matlab/) action, you need a [MATLAB batch licensing token](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/alternates/non-interactive/MATLAB-BATCH.md#matlab-batch-licensing-token) if your project is private or if your workflow uses 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](https://www.mathworks.com/support/batch-tokens.html) form.
57
52
58
53
To use a MATLAB batch licensing token:
@@ -81,31 +76,34 @@ jobs:
81
76
```
82
77
83
78
## Run MATLAB Build
84
-
85
79
When you define your workflow in the `.github/workflows` directory of your repository, specify the **Run MATLAB Build** action as `matlab-actions/run-build@v3`. The action accepts optional inputs.
| `tasks` | <p>(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 action runs the default tasks in your build file as well as all the tasks on which they depend. By default, the action looks for a build file named `buildfile.m` in the root of your repository.</p><p>MATLAB exits with exit code 0 if the tasks run without error. Otherwise, MATLAB terminates with a nonzero exit code, which causes the action to fail.</p><p>**Example:** `tasks: test`<br/>**Example:** `tasks: compile test`<br/>**Example:** `tasks: check test("myFolder",OutputDetail="concise") archive("source.zip")`</p> |
90
84
| `build-options` | <p>(Optional) MATLAB build options, specified as a list of options separated by spaces. The action supports the same [options](https://www.mathworks.com/help/matlab/ref/buildtool.html#mw_50c0f35e-93df-4579-963d-f59f2fba1dba) that you can pass to the `buildtool` command.</p><p>**Example:** `build-options: -continueOnFailure`<br/>**Example:** `build-options: -continueOnFailure -skip test`</p> |
91
-
| `generate-summary` | <p>(Optional) Option to generate summaries of build and test results in the GitHub job summary, specified as `true` or `false`. By default, the value is `true`. If you specify a value of `false`, the action does not generate build and test summaries in the GitHub job summary. This input is useful for controlling the information displayed in the GitHub job summary.</p><p>When the value is `true`, the action generates a summary of build results. If you have a MATLAB Test™ license and your MATLAB build runs tests using a [`matlab.buildtool.tasks.TestTask`](https://www.mathworks.com/help/matlab/ref/matlab.buildtool.tasks.testtask-class.html) instance, then the action also generates a summary of test results in the GitHub job summary.</p><p>**Example:** `generate-summary: false`</p> |
85
+
| `generate-summary` | <p>(Optional) Option to generate summaries of build and test results in the GitHub job summary, specified as `true` or `false`. By default, the value is `true`. If you specify a value of `false`, the action does not generate build and test summaries in the GitHub job summary. This input is useful for controlling the information displayed in the GitHub job summary.</p><p>For more information about the build summary, see [View Build Results](#view-build-results).</p><p>**Example:** `generate-summary: false`</p> |
92
86
| `startup-options` | <p>(Optional) MATLAB startup options, specified as a list of options separated by spaces. For more information about startup options, see [Commonly Used Startup Options](https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html).</p><p>Using this input to specify the `-batch` or `-r` option is not supported.</p><p>**Example:** `startup-options: -nojvm`<br/>**Example:** `startup-options: -nojvm -logfile output.log`</p> |
93
87
94
-
## Notes
88
+
## View Build Results
89
+
If you run a MATLAB build and the `generate-summary` input is `true`, you can view the MATLAB build results in the GitHub job summary. After your build runs, the **MATLAB Build Results** table in the summary provides information about each task that was part of the build.
If you have a MATLAB Test™ license and your MATLAB build runs tests using a [`matlab.buildtool.tasks.TestTask`](https://www.mathworks.com/help/matlab/ref/matlab.buildtool.tasks.testtask-class.html) instance, then the action also generates a summary of test results in the GitHub job summary. For more information about the test summary, see [View Test and Coverage Results](https://github.com/matlab-actions/run-tests/#view-test-and-coverage-results).
95
94
95
+
## Notes
96
96
- By default, when you use the **Run MATLAB Build** action, the root of your repository serves as the MATLAB startup folder. To run your MATLAB build using a different folder, specify the `-sd` startup option in the action.
97
97
- The **Run MATLAB Build** action uses the `-batch` option to invoke the [`buildtool`](https://www.mathworks.com/help/matlab/ref/buildtool.html) command. MATLAB settings do not persist across different MATLAB sessions launched with the `-batch` option. To run code that requires the same settings, use a single action.
98
98
- When you use the **Run MATLAB Build** action, you execute third-party code that is licensed under separate terms.
99
99
100
100
## See Also
101
-
102
101
- [Action for Running MATLAB Tests](https://github.com/matlab-actions/run-tests/)
103
102
- [Action for Running MATLAB Commands](https://github.com/matlab-actions/run-command)
104
103
- [Action for Setting Up MATLAB](https://github.com/matlab-actions/setup-matlab/)
105
104
- [Continuous Integration with MATLAB and Simulink](https://www.mathworks.com/solutions/continuous-integration.html)
106
105
107
106
## Feedback and Support
108
-
109
107
If you encounter a product licensing issue, consider requesting a MATLAB batch licensing token to use in your workflow. For more information, see [Use MATLAB Batch Licensing Token](#use-matlab-batch-licensing-token).
110
108
111
109
If you have an enhancement request or other feedback about this action, create an issue on the [Issues](https://github.com/matlab-actions/run-build/issues) page.
0 commit comments