Skip to content

Commit 632b517

Browse files
mw-hrastegamw-hrastega
authored
documenting batch token licensing
1 parent e74fb66 commit 632b517

File tree

1 file changed

+65
-28
lines changed

1 file changed

+65
-28
lines changed

‎README.md‎

Lines changed: 65 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
# Action for Setting Up MATLAB
22

3-
The [Setup MATLAB](#set-up-matlab) action enables you to run MATLAB® code and Simulink® models with a specific version of MATLAB. When you specify this action as part of your workflow, the action sets up your preferred MATLAB release (R2021a or later) on a Linux®, Windows®, or macOS runner. If you do not specify a release, the action sets up the latest release of MATLAB. As part of the setup process, the action prepends MATLAB to the `PATH` system environment variable.
3+
The [Setup MATLAB](#set-up-matlab) action enables you to set up MATLAB® and other MathWorks® products on a [GitHub®-hosted](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners) runner. When you specify this action as part of your workflow, the action sets up your preferred MATLAB release (R2021a or later) on a Linux®, Windows®, or macOS runner. If you do not specify a release, the action sets up the latest release of MATLAB. As part of the setup process, the action prepends MATLAB to the `PATH` system environment variable.
44

55
## Examples
66
Once you set up MATLAB on a runner, you can build and test your MATLAB project as part of your workflow. To execute code on the runner, include the [Run MATLAB Build](https://github.com/matlab-actions/run-build/), [Run MATLAB Tests](https://github.com/matlab-actions/run-tests/), or [Run MATLAB Command](https://github.com/matlab-actions/run-command/) action in your workflow.
77

8-
### Run MATLAB Build on GitHub-Hosted Runner
9-
Use a [GitHub®-hosted runner](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners) to run a task and its depended-on tasks that are specified in a file named `buildfile.m` in the root of your repository. Because the `"test"` task in this example runs the tests authored using the MATLAB unit testing framework as well as Simulink Test™, you must set up Simulink and Simulink Test in addition to MATLAB. To run tasks using the MATLAB build tool, specify the [Run MATLAB Build](https://github.com/matlab-actions/run-build/) action in your workflow.
8+
### Run Default Tasks in Build File
9+
Using the latest release of MATLAB on a GitHub-hosted runner, 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 set up the latest release of MATLAB on the runner, specify the **Setup MATLAB** action in your workflow. To run the tasks, specify the [Run MATLAB Build](https://github.com/matlab-actions/run-build/) action.
1010

1111
```yaml
12-
name: Run MATLAB Build on GitHub-Hosted Runner
12+
name: Run Default Tasks in Build File
1313
on: [push]
1414
jobs:
1515
my-job:
@@ -20,41 +20,41 @@ jobs:
2020
uses: actions/checkout@v4
2121
- name: Set up MATLAB
2222
uses: matlab-actions/setup-matlab@v2
23-
with:
24-
products: Simulink Simulink_Test
2523
- name: Run build
2624
uses: matlab-actions/run-build@v2
27-
with:
28-
tasks: test
2925
```
3026
31-
### Run MATLAB Tests on GitHub-Hosted Runner
32-
Use a GitHub-hosted runner to run the tests in your [MATLAB project](https://www.mathworks.com/help/matlab/projects.html) and generate test results in JUnit-style XML format and code coverage results in Cobertura XML format. To run the tests and generate the artifacts, specify the [Run MATLAB Tests](https://github.com/matlab-actions/run-tests/) action in your workflow.
27+
### Run MATLAB and Simulink Tests
28+
Run your MATLAB and Simulink tests in parallel (requires Parallel Computing Toolbox™) using the latest release of the required products on a GitHub-hosted runner. To set up the latest release of MATLAB, Simulink, Simulink Test, and Parallel Computing Toolbox on the runner, specify the **Setup MATLAB** action with its `products` input in your workflow. To run the tests in parallel, specify the [Run MATLAB Tests](https://github.com/matlab-actions/run-tests/) action with its `use-parallel` input specified as `true`.
3329

34-
```yaml
35-
name: Run MATLAB Tests on GitHub-Hosted Runner
30+
```YAML
31+
name: Run MATLAB and Simulink Tests
3632
on: [push]
3733
jobs:
3834
my-job:
39-
name: Run MATLAB Tests and Generate Artifacts
35+
name: Run Tests in Parallel
4036
runs-on: ubuntu-latest
4137
steps:
4238
- name: Check out repository
4339
uses: actions/checkout@v4
44-
- name: Set up MATLAB
40+
- name: Set up products
4541
uses: matlab-actions/setup-matlab@v2
46-
- name: Run tests and generate artifacts
42+
with:
43+
products: >
44+
Simulink
45+
Simulink_Test
46+
Parallel_Computing_Toolbox
47+
- name: Run tests
4748
uses: matlab-actions/run-tests@v2
4849
with:
49-
test-results-junit: test-results/results.xml
50-
code-coverage-cobertura: code-coverage/coverage.xml
51-
```
50+
use-parallel: true
51+
```
5252

53-
### Run MATLAB Script on GitHub-Hosted Runner
54-
Use a GitHub-hosted runner to run the commands in a file named `myscript.m` in the root of your repository. To run the script, specify the [Run MATLAB Command](https://github.com/matlab-actions/run-command/) action in your workflow.
53+
### Run MATLAB Script
54+
Using the latest release of MATLAB on a GitHub-hosted runner, run a script named `myscript.m` in the root of your repository. To set up the latest release of MATLAB on the runner, specify the **Setup MATLAB** action in your workflow. To run the script, specify the [Run MATLAB Command](https://github.com/matlab-actions/run-command/) action.
5555

5656
```yaml
57-
name: Run MATLAB Script on GitHub-Hosted Runner
57+
name: Run MATLAB Script
5858
on: [push]
5959
jobs:
6060
my-job:
@@ -71,11 +71,39 @@ jobs:
7171
command: myscript
7272
```
7373

74-
### Run MATLAB Build Across Different Platforms
74+
### Use MATLAB Batch Licensing Token
75+
On a GitHub-hosted runner, 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 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](https://www.mathworks.com/support/batch-tokens.html) form.
76+
77+
To use a MATLAB batch licensing token:
78+
79+
1. Set the token as a secret. For more information about secrets, see [Using secrets in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
80+
2. Map the secret to an environment variable named `MLM_LICENSE_TOKEN` in your workflow.
81+
82+
For example, use the latest release of MATLAB on a GitHub-hosted runner to run the tests in your private project. To install the latest release of MATLAB on the runner, specify the **Setup MATLAB** action in your workflow. To run the tests, specify the [Run MATLAB Tests](https://github.com/matlab-actions/run-tests/) action. In this example, `MyToken` is the name of the secret that holds the batch licensing token.
83+
84+
```YAML
85+
name: Use MATLAB Batch Licensing Token
86+
on: [push]
87+
env:
88+
MLM_LICENSE_TOKEN: ${{ secrets.MyToken }}
89+
jobs:
90+
my-job:
91+
name: Run MATLAB Tests in Private Project
92+
runs-on: ubuntu-latest
93+
steps:
94+
- name: Check out repository
95+
uses: actions/checkout@v4
96+
- name: Set up MATLAB
97+
uses: matlab-actions/setup-matlab@v2
98+
- name: Run tests
99+
uses: matlab-actions/run-tests@v2
100+
```
101+
102+
### Build Across Multiple Platforms
75103
The **Setup MATLAB** action supports the Linux, Windows, and macOS platforms. Define a matrix of job configurations to run a build using the MATLAB build tool on all the supported platforms. This workflow runs three jobs, one for each value in the variable `os`. For more information about matrices, see [Using a matrix for your jobs](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs).
76104

77105
```YAML
78-
name: Run MATLAB Build Across Different Platforms
106+
name: Build Across Multiple Platforms
79107
on: [push]
80108
jobs:
81109
my-job:
@@ -100,12 +128,21 @@ When you define your workflow in the `.github/workflows` directory of your repos
100128

101129
| Input | Description |
102130
|-----------|-------------|
103-
| `release` | <p>(Optional) MATLAB release to set up. You can specify R2021a or a later release. By default, the value of `release` is `latest`, which corresponds to the latest release of MATLAB.<p/><p>**Example**: `release: R2023a`<br/>**Example**: `release: latest`</p>
104-
| `products` | <p>(Optional) Products to set up in addition to MATLAB, specified as a list of product names separated by spaces. You can specify `products` to set up most MathWorks&reg; products and support packages. For example, `products: Deep_Learning_Toolbox` sets up Deep Learning Toolbox&trade; in addition to MATLAB.</p><p>The action uses [MATLAB Package Manager](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md) (`mpm`) to set up products. For a list of supported products and their correctly formatted names, see [Product Installation Options](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md#product-installation-options).</p> <p>:information_source: **Note:** If you use this input to set up transformation products, such as MATLAB Coder&trade; and MATLAB Compiler&trade;, the action does not automatically license such products for you.<p/><p>**Example**: `products: Simulink`</br>**Example:** `products: Simulink Deep_Learning_Toolbox`</p>
105-
| `cache` | <p>(Optional) Option to enable caching with GitHub&reg; Actions, specified as `false` or `true`. By default, the value is `false` and the action does not store MATLAB and the specified products in a GitHub Actions cache for future use. For more information about caching with GitHub Actions, see [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows).<p/><p>**Example**: `cache: true`</p>
131+
| `release` | <p>(Optional) MATLAB release to set up. You can specify R2021a or a later release. By default, the value of `release` is `latest`, which corresponds to the latest release of MATLAB.</p><p>**Example**: `release: R2023b`<br/>**Example**: `release: latest`</p>
132+
| `products` | <p>(Optional) Products to set up in addition to MATLAB, specified as a list of product names separated by spaces. You can specify `products` to set up most MathWorks products and support packages. For example, `products: Deep_Learning_Toolbox` sets up Deep Learning Toolbox&trade; in addition to MATLAB.</p><p>The action uses [MATLAB Package Manager](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md) (`mpm`) to set up products. For a list of supported products and their formatted names, see [Product Installation Options](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md#product-installation-options).</p><p>For an example of how to use the `products` input, see [Run MATLAB and Simulink Tests](#run-matlab-and-simulink-tests).</p><p>**Example**: `products: Simulink`<br/>**Example:** `products: Simulink Deep_Learning_Toolbox`</p>
133+
| `cache` | <p>(Optional) Option to enable caching with GitHub Actions, specified as `false` or `true`. By default, the value is `false` and the action does not store MATLAB and the specified products in a GitHub Actions cache for future use. For more information about caching with GitHub Actions, see [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows).</p><p>**Example**: `cache: true`</p>
134+
135+
#### Licensing
136+
Product licensing for your workflow depends on your project visibility as well as the type of products to set up:
137+
138+
- Public project — If your workflow does not include transformation products, such as MATLAB Coder and MATLAB Compiler, then the action automatically licenses any products that you set up. If your workflow includes transformation products, you can request 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) by submitting the [MATLAB Batch Licensing Pilot](https://www.mathworks.com/support/batch-tokens.html) form.
139+
- Private project — The action does not automatically license any products for you. You can request a batch licensing token by submitting the [MATLAB Batch Licensing Pilot](https://www.mathworks.com/support/batch-tokens.html) form.
140+
141+
To use a MATLAB batch licensing token, first set it as a [secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions). Then, map the secret to an environment variable named `MLM_LICENSE_TOKEN` in your workflow. For an example, see [Use MATLAB Batch Licensing Token](#use-matlab-batch-licensing-token).
106142

107143
## Notes
108-
When you use the **Setup MATLAB** action, you execute third-party code that is licensed under separate terms.
144+
- The **Setup MATLAB** action automatically includes the [MATLAB batch licensing executable](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/alternates/non-interactive/MATLAB-BATCH.md) (`matlab-batch`). To use a MATLAB batch licensing token in a workflow that does not use this action, you must first download the executable and add it to the system path.
145+
- When you use the **Setup MATLAB** action, you execute third-party code that is licensed under separate terms.
109146

110147
## See Also
111148
- [Action for Running MATLAB Builds](https://github.com/matlab-actions/run-build/)
@@ -114,4 +151,4 @@ When you use the **Setup MATLAB** action, you execute third-party code that is l
114151
- [Continuous Integration with MATLAB and Simulink](https://www.mathworks.com/solutions/continuous-integration.html)
115152

116153
## Contact Us
117-
If you have any questions or suggestions, please contact MathWorks at [continuous-integration@mathworks.com](mailto:continuous-integration@mathworks.com).
154+
If you have any questions or suggestions, contact MathWorks at [continuous-integration@mathworks.com](mailto:continuous-integration@mathworks.com).

0 commit comments

Comments
 (0)