Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/matlab-actions/run-build

Run a build using the MATLAB build tool.
https://github.com/matlab-actions/run-build

mathworks matlab simulink

Last synced: 18 days ago
JSON representation

Run a build using the MATLAB build tool.

Host: GitHub
URL: https://github.com/matlab-actions/run-build
Owner: matlab-actions
License: bsd-3-clause
Created: 2022-08-31T16:01:49.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2024-08-30T15:37:21.000Z (4 months ago)
Last Synced: 2024-12-01T02:41:35.359Z (22 days ago)
Topics: mathworks, matlab, simulink
Language: TypeScript
Homepage:
Size: 41.4 MB
Stars: 14
Watchers: 4
Forks: 5
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: license.txt
- Security: SECURITY.md

Awesome Lists containing this project

README

# Action for Running MATLAB Builds

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

The [Run MATLAB Build](#run-matlab-build) action enables you to invoke the MATLAB build tool on a [self-hosted](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) or [GitHub®-hosted](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners) runner:
- To use a self-hosted runner, you must set up a computer with MATLAB as your self-hosted runner and register the runner with GitHub Actions. The runner uses the topmost MATLAB release on the system path to execute your workflow.
- To use a GitHub-hosted runner, you must include the [Setup MATLAB](https://github.com/matlab-actions/setup-matlab/) action in your workflow to set up your preferred MATLAB release (R2021a or later) on the runner.

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

### Run Default Tasks in Build File
On a self-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 run the tasks, specify the **Run MATLAB Build** action in your workflow.

```yaml
name: Run Default Tasks in Build File
on: [push]
jobs:
my-job:
name: Run MATLAB Build
runs-on: self-hosted
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Run build
uses: matlab-actions/run-build@v2
```

### Run Specified Task in Build File
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.

```yaml
name: Run Specified Task in Build File
on: [push]
jobs:
my-job:
name: Run MATLAB Build
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 build
uses: matlab-actions/run-build@v2
with:
tasks: mytask
```

### 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 a MATLAB build in your private project. 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. 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 Build 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 build
uses: matlab-actions/run-build@v2
```

## Run MATLAB Build
When you define your workflow in the `.github/workflows` directory of your repository, specify the **Run MATLAB Build** action as `matlab-actions/run-build@v2`. The action accepts optional inputs.

Input | Description
------------------------- | ---------------
`tasks` |

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

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.

**Example:** `tasks: test`
**Example:** `tasks: compile test`
**Example:** `tasks: check test("myFolder",OutputDetail="concise") archive("source.zip")`

`build-options` |

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

**Example:** `build-options: -continueOnFailure`
**Example:** `build-options: -continueOnFailure -skip test`

`startup-options` |

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

Using this input to specify the `-batch` or `-r` option is not supported.

**Example:** `startup-options: -nojvm`
**Example:** `startup-options: -nojvm -logfile output.log`

## Notes
* 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.
* The **Run MATLAB Build** action uses the `-batch` option to invoke the [`buildtool`](https://www.mathworks.com/help/matlab/ref/buildtool.html) command. Preferences do not persist across different MATLAB sessions launched with the `-batch` option. To run code that requires the same preferences, use a single action.
* When you use the **Run MATLAB Build** action, you execute third-party code that is licensed under separate terms.

## See Also
- [Action for Running MATLAB Tests](https://github.com/matlab-actions/run-tests/)
- [Action for Running MATLAB Commands](https://github.com/matlab-actions/run-command)
- [Action for Setting Up MATLAB](https://github.com/matlab-actions/setup-matlab/)
- [Continuous Integration with MATLAB and Simulink](https://www.mathworks.com/solutions/continuous-integration.html)

## Contact Us
If you have any questions or suggestions, contact MathWorks® at [[email protected]](mailto:[email protected]).