Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

updating README in preparation for matlab-actions/run-build@v2 #17

Merged
merged 7 commits into from
Feb 13, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 15 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,13 @@

Starting in R2022b, the MATLAB® build tool provides a standard programming interface to create and run software-build 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/free-pro-team@latest/actions/hosting-your-own-runners/about-self-hosted-runners) or [GitHub®-hosted](https://docs.github.com/en/free-pro-team@latest/actions/reference/specifications-for-github-hosted-runners) runner:

- To use a self-hosted runner, you must set up a computer with MATLAB as your runner. The runner uses the topmost MATLAB version 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 MATLAB on the runner. Currently, this action is available only for public projects. It does not set up transformation products, such as MATLAB Coder™ and MATLAB Compiler™.
The [Run MATLAB Build](#run-matlab-build) action enables you to invoke the MATLAB build tool on a self-hosted or GitHub®-hosted runner. The action uses the topmost MATLAB version on the system path.

## 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 specified in a file named `buildfile.m` in the root of your repository.
Use the **Run MATLAB Build** action to run a build using the MATLAB build tool. You can use this action to run the tasks specified in a 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 MATLAB Build on Self-Hosted Runner
Use a self-hosted runner to run the default tasks in your build plan as well as all the tasks on which they depend.
Use a [self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) to run the default tasks in your build plan as well as all the tasks on which they depend.

```yaml
name: Run MATLAB Build on Self-Hosted Runner
Expand All @@ -23,13 +19,13 @@ jobs:
runs-on: self-hosted
steps:
- name: Check out repository
uses: actions/checkout@v3
uses: actions/checkout@v4
- name: Run build
uses: matlab-actions/run-build@v1
uses: matlab-actions/run-build@v2
Comment on lines -28 to +24
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think adding build-options to the matlab-actions/run-build action would be a MINOR release instead of a MAJOR.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi, @mw-kapilg. The version bump is not due to the new option; it's because of migrating to batch tokens. In other words, this release will include your work on build options as well as @davidbuzinski 's efforts on batch tokens.

```

### Run MATLAB Build on GitHub-Hosted Runner
Before you run MATLAB code or Simulink models on a GitHub-hosted runner, first use the [Setup MATLAB](https://github.com/matlab-actions/setup-matlab/) action. The action sets up your specified MATLAB release (R2020a or later) on a Linux® virtual machine. If you do not specify a release, the action sets up the latest release of MATLAB. To use the **Run MATLAB Build** action, you need MATLAB R2022b or a later release.
Before you run MATLAB code or Simulink models on a [GitHub-hosted runner](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners), first use the [Setup MATLAB](https://github.com/matlab-actions/setup-matlab/) action. The action sets up your specified 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.

For example, set up the latest release of MATLAB on a GitHub-hosted runner, and then use the **Run MATLAB Build** action to run a specific task and the tasks on which it depends.

Expand All @@ -42,35 +38,36 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v3
uses: actions/checkout@v4
- name: Set up MATLAB
uses: matlab-actions/setup-matlab@v1
uses: matlab-actions/setup-matlab@v2
- name: Run build
uses: matlab-actions/run-build@v1
uses: matlab-actions/run-build@v2
with:
tasks: mytask
```

## 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@v1`. The action accepts optional inputs.
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) Space-separated list of tasks to run. If not specified, the action runs the default tasks in `buildfile.m` as well as all the tasks on which they depend.</br>MATLAB exits with exit code 0 if the tasks run without error. Otherwise, MATLAB terminates with a nonzero exit code, which causes the workflow to fail.<br/>**Example:** `tasks: test`</br>**Example:** `tasks: compile test`
`startup-options` | (Optional) MATLAB startup options. If you specify more than one option, use a space to separate them. For more information about startup options, see [Commonly Used Startup Options](https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html).<br/>Using this input to specify the `-batch` or `-r` option is not supported.<br/>**Example:** `startup-options: -nojvm`<br/>**Example:** `startup-options: -nojvm -logfile "output.log"`
`tasks` | <p>(Optional) Tasks to run, specified as a list of task names separated by spaces. If you do not specify `tasks`, the action runs the default tasks in `buildfile.m` as well as all the tasks on which they depend.</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`</p>
`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 when running a MATLAB build.<p/><p>**Example:** `build-options: -continueOnFailure`<br/>**Example:** `build-options: -continueOnFailure -skip test`</p>
`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>

When you use this action, a file named `buildfile.m` must be in the project root directory.

## Notes
* The **Run MATLAB Build** action uses the `-batch` option to invoke the [`buildtool`](https://www.mathworks.com/help/matlab/ref/buildtool.html) command noninteractively. 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.
* 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
- [Create and Run Tasks Using Build Tool](https://www.mathworks.com/help/matlab/matlab_prog/create-and-run-tasks-using-build-tool.html)
- [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 on GitHub-Hosted Runner](https://github.com/matlab-actions/setup-matlab/)
- [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
Expand Down
Loading