Skip to content

Commit

Permalink
updating examples
Browse files Browse the repository at this point in the history
  • Loading branch information
@mw-hrastega
mw-hrastega authored May 9, 2024
1 parent e74fb66 commit 10a2999
Showing 1 changed file with 55 additions and 27 deletions.
82 changes: 55 additions & 27 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# Action for Setting Up MATLAB

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

## Examples
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.

### Run MATLAB Build on GitHub-Hosted Runner
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.
### Run Default Tasks in Build File
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.

```yaml
name: Run MATLAB Build on GitHub-Hosted Runner
name: Run Default Tasks in Build File
on: [push]
jobs:
my-job:
Expand All @@ -20,41 +20,41 @@ jobs:
uses: actions/checkout@v4
- name: Set up MATLAB
uses: matlab-actions/setup-matlab@v2
with:
products: Simulink Simulink_Test
- name: Run build
uses: matlab-actions/run-build@v2
with:
tasks: test
```
### Run MATLAB Tests on GitHub-Hosted Runner
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.
### Run MATLAB and Simulink Tests
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`.

```yaml
name: Run MATLAB Tests on GitHub-Hosted Runner
```YAML
name: Run MATLAB and Simulink Tests in Parallel
on: [push]
jobs:
my-job:
name: Run MATLAB Tests and Generate Artifacts
name: Run MATLAB and Simulink Tests
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up MATLAB
- name: Set up products
uses: matlab-actions/setup-matlab@v2
- name: Run tests and generate artifacts
with:
products: >
Simulink
Simulink_Test
Parallel_Computing_Toolbox
- name: Run tests
uses: matlab-actions/run-tests@v2
with:
test-results-junit: test-results/results.xml
code-coverage-cobertura: code-coverage/coverage.xml
```
use-parallel: true
```

### Run MATLAB Script on GitHub-Hosted Runner
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.
### Run MATLAB Script
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.

```yaml
name: Run MATLAB Script on GitHub-Hosted Runner
name: Run MATLAB Script
on: [push]
jobs:
my-job:
Expand All @@ -71,11 +71,39 @@ jobs:
command: myscript
```

### Run MATLAB Build Across Different Platforms
### Use MATLAB Batch Licensing Token
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.

To use a MATLAB batch licensing token:

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).
2. Map the secret to an environment variable named `MLM_LICENSE_TOKEN` in your workflow.

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.

```YAML
name: Use MATLAB Batch Licensing Token
on: [push]
env:
MLM_LICENSE_TOKEN: ${{ secrets.MyToken }}
jobs:
my-job:
name: Run MATLAB Tests in Private Project
runs-on: ubuntu-latest
steps:
- name: Check out repository
- uses: actions/checkout@v4
- name: Set up MATLAB
- uses: matlab-actions/setup-matlab@v2
- name: Run tests
- uses: matlab-actions/run-tests@v2
```

### Build Across Multiple Platforms
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).

```YAML
name: Run MATLAB Build Across Different Platforms
name: Build Across Multiple Platforms
on: [push]
jobs:
my-job:
Expand All @@ -100,9 +128,9 @@ When you define your workflow in the `.github/workflows` directory of your repos

| Input | Description |
|-----------|-------------|
| `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>
| `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>
| `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>
| `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>
| `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 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>
| `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>

## Notes
When you use the **Setup MATLAB** action, you execute third-party code that is licensed under separate terms.
Expand All @@ -114,4 +142,4 @@ When you use the **Setup MATLAB** action, you execute third-party code that is l
- [Continuous Integration with MATLAB and Simulink](https://www.mathworks.com/solutions/continuous-integration.html)

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

0 comments on commit 10a2999

Please sign in to comment.