Skip to content
Open
Show file tree
Hide file tree
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
4 changes: 2 additions & 2 deletions .circleci/CrossPlatformBuilder.yml
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,7 +10,7 @@ executors:
image: default
macos:
macos:
xcode: 15.4.0
xcode: 16.4.0
windows:
win/default

Expand DownExpand Up@@ -48,4 +48,4 @@ workflows:
matrix:
parameters:
os: [linux, macos, windows]
release: ["R2024b", "R2025a"]
Copy link
Member

Choose a reason for hiding this comment

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

Instead of updating the releases frequently, does it make sense to have one fixed release and other as 'latest'?

release: ["R2025a", "R2025b"]
49 changes: 49 additions & 0 deletions .circleci/TestSplitting.yml
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
version: 2.1
orbs:
matlab: mathworks/matlab@1
win: circleci/windows@5

# Define the execution environments for different operating systems
executors:
linux:
machine:
image: default
macos:
macos:
xcode: 16.4.0
windows:
win/default

jobs:
split-and-run-test:
parameters:
os:
type: executor
executor: << parameters.os >>
# Use parallelism to split tests across multiple containers
parallelism: 2
steps:
- checkout

# Install MATLAB and required products
- matlab/install:
products: >
MATLAB_Compiler_SDK
MATLAB_Test
# Builds mex file and Python package from MATLAB function
- matlab/run-build:
tasks: mex buildPythonPackage

# Run MATLAB tests, splitting them across parallel containers
Copy link
Member

Choose a reason for hiding this comment

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

I'm curious - does CircleCI handle test splitting by distributing them across multiple separate machines, or are the tests simply divided among different cores on the same machine?

- matlab/run-tests:
select-by-name: $(circleci tests glob "tests/**/*.m" | circleci tests split | awk -F'[\\\\/.]' '{print $(NF-1) "/*"}')
Copy link
Member

Choose a reason for hiding this comment

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

I believe this configuration currently splits the tests alphabetically by default. Would it make sense to add comments or examples showing how to split tests based on file size or previous timing data as well?


workflows:
test-splitting-build:
jobs:
# A job will run for each OS present in the matrix
- split-and-run-test:
matrix:
parameters:
os: [linux, macos, windows]
2 changes: 1 addition & 1 deletion .circleci/ToolboxDistribution.yml
Original file line numberDiff line numberDiff line change
Expand Up@@ -11,7 +11,7 @@ executors:
image: default
macos:
macos:
xcode: 15.4.0
xcode: 16.4.0
windows:
win/default

Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/CrossPlatformBuilder.yml
Original file line numberDiff line numberDiff line change
Expand Up@@ -20,7 +20,7 @@ jobs:
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
release: [R2024b, R2025a]
release: [R2025a, R2025b]

# The type of runner that the job will run on
runs-on: ${{matrix.os }}
Expand Down
20 changes: 10 additions & 10 deletions AzureDevOps/CrossPlatformBuilder.yml
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,24 +3,24 @@ jobs:
# Matrix strategy to run builds across different OS and MATLAB release combinations
strategy:
matrix:
linux-R2024b:
imageName: ubuntu-latest
release: R2024b
linux-R2025a:
imageName: ubuntu-latest
release: R2025a
mac-R2024b:
imageName: macOS-latest
release: R2024b
linux-R2025b:
imageName: ubuntu-latest
release: R2025b
mac-R2025a:
imageName: macOS-latest
release: R2025a
windows-R2024b:
imageName: windows-latest
release: R2024b
mac-R2025b:
imageName: macOS-latest
release: R2025b
windows-R2025a:
imageName: windows-latest
release: R2025a
release: R2025a
windows-R2025b:
imageName: windows-latest
release: R2025b
pool:
vmImage: $(imageName)
steps:
Expand Down
2 changes: 1 addition & 1 deletion Jenkins/CrossPlatformBuilder/Jenkinsfile
Original file line numberDiff line numberDiff line change
Expand Up@@ -11,7 +11,7 @@ pipeline{
}
axis{
name 'RELEASE'
values 'R2024b', 'R2025a'
values 'R2025a', 'R2025b'
}
}
stages{
Expand Down
4 changes: 2 additions & 2 deletions Jenkins/ToolboxDistribution/Jenkinsfile
Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,7 @@ pipeline{
agent{label "${OS}"}

tools{
matlab 'R2024b'
matlab 'R2025b'
}

steps{
Expand DownExpand Up@@ -44,7 +44,7 @@ pipeline{
}

tools{
matlab 'R2024b'
matlab 'R2025b'
}

steps{
Expand Down
28 changes: 21 additions & 7 deletions README.md
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,7 @@
This repository includes examples of advanced workflows in MATLAB<sup>&reg;</sup> for common CI platforms. For example, you can use matrix-build templates to package and distribute toolboxes across operating systems or build and deploy standalone applications for multiple MATLAB releases. The repository includes all the required source code, tests, and configuration files for each workflow and CI platform.

This repository provides workflow examples for these platforms:

* [Azure<sup>&reg;</sup> DevOps](https://marketplace.visualstudio.com/items?itemName=MathWorks.matlab-azure-devops-extension)
* [CircleCI<sup>&reg;</sup>](https://github.com/mathworks/matlab-circleci-orb/blob/master/README.md)
* [GitHub<sup>&reg;</sup> Actions](https://github.com/matlab-actions)
Expand All@@ -16,33 +17,43 @@ For starter workflows, use the [`ci-configuration-examples`](https://github.com/

The repository contains examples for packaging and distributing a toolbox, building and uploading Python<sup>&reg;</sup> packages, and running tests across multiple build agents.

- **Package and Distribute Toolbox**: Using a matrix build across multiple platforms, compile, link, and test your C source files to produce a binary MEX file per operating system. Then, bundle the resulting binaries into a toolbox and distribute it as a GitHub release.
* **Package and Distribute Toolbox**: Using a matrix build across multiple platforms, compile, link, and test your C source files to produce a binary MEX file per operating system. Then, bundle the resulting binaries into a toolbox and distribute it as a GitHub release.

To access the configuration files for this workflow, follow the links in this table.

| **Platform** | **File Path** |
|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| Azure DevOps| [`AzureDevOps/ToolboxDistribution.yml`](https://github.com/mathworks/advanced-ci-configuration-examples/blob/main/AzureDevOps/ToolboxDistribution.yml) |
| CircleCI| [`.circleci/ToolboxDistribution.yml`](https://github.com/mathworks/advanced-ci-configuration-examples/blob/main/.circleci/ToolboxDistribution.yml) |
| GitHub Actions| [`.github/workflows/ToolboxDistribution.yml`](https://github.com/mathworks/advanced-ci-configuration-examples/blob/main/.github/workflows/ToolboxDistribution.yml) |
| Jenkins | [`Jenkins/ToolboxDistribution/Jenkinsfile`](https://github.com/mathworks/advanced-ci-configuration-examples/blob/main/Jenkins/ToolboxDistribution/Jenkinsfile) |

- **Build and Upload Python Packages**: Using a matrix build across multiple platforms and MATLAB releases, build python packages by compiling MATLAB functions (requires MATLAB Compiler SDK&trade;) and upload the resulting packages as artifacts.
* **Build and Upload Python Packages**: Using a matrix build across multiple platforms and MATLAB releases, build python packages by compiling MATLAB functions (requires MATLAB Compiler SDK&trade;) and upload the resulting packages as artifacts.

To access the configuration files for this workflow, follow the links in this table.

| **Platform** | **File Path** |
|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| Azure DevOps| [`AzureDevOps/CrossPlatformBuilder.yml`](https://github.com/mathworks/advanced-ci-configuration-examples/blob/main/AzureDevOps/CrossPlatformBuilder.yml) |
| CircleCI| [`.circleci/CrossPlatformBuilder.yml`](https://github.com/mathworks/advanced-ci-configuration-examples/blob/main/.circleci/CrossPlatformBuilder.yml) |
| GitHub Actions| [`.github/workflows/CrossPlatformBuilder.yml`](https://github.com/mathworks/advanced-ci-configuration-examples/blob/main/.github/workflows/CrossPlatformBuilder.yml) |
| Jenkins | [`Jenkins/CrossPlatformBuilder/Jenkinsfile`](https://github.com/mathworks/advanced-ci-configuration-examples/blob/main/Jenkins/CrossPlatformBuilder/Jenkinsfile) |

- **Run Tests Across Multiple Agents**: Use the [parallel strategy](https://learn.microsoft.com/en-us/azure/devops/pipelines/test/parallel-testing-any-test-runner?view=azure-devops) in Azure DevOps to run tests across multiple agents and speed up the testing process. For configuration details, see the example in [`AzureDevOps/ParallelStrategy/ParallelStrategy.yml`](https://github.com/mathworks/advanced-ci-configuration-examples/blob/main/AzureDevOps/ParallelStrategy/ParallelStrategy.yml).
* **Run Tests Across Multiple Agents**: Use the [parallel strategy](https://learn.microsoft.com/en-us/azure/devops/pipelines/test/parallel-testing-any-test-runner?view=azure-devops) in Azure DevOps or [test splitting](https://circleci.com/docs/guides/optimize/parallelism-faster-jobs/) in CircleCI to run tests across multiple agents and speed up the testing process.

To access the configuration files for this workflow, follow the links in this table.

| **Platform** | **File Path** |
|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| Azure DevOps| [`AzureDevOps/ParallelStrategy/ParallelStrategy.yml`](https://github.com/mathworks/advanced-ci-configuration-examples/blob/main/AzureDevOps/ParallelStrategy/ParallelStrategy.yml) |
| CircleCI| [`.circleci/TestSplitting.yml`](https://github.com/mathworks/advanced-ci-configuration-examples/blob/main/.circleci/TestSplitting.yml) |

<br>

## Get Started

Here's how to quickly get this repository running on a CI system:

1. Fork the repository to your own GitHub account.
2. Go to one of the supported CI platforms and install the available CI integration for MATLAB. (GitHub Actions does not require this step.)
3. Create a new CI job using your forked repository. You need to specify which file to use based on the workflow you intend to run.
Expand All@@ -53,22 +64,25 @@ That's really it!
<br>

## Licensing

Product licensing for your workflow depends on your project visibility as well as the types of products the workflow uses:

- Public project — The CI integration for MATLAB automatically licenses all products for you, except for transformation products, such as MATLAB Coder&trade; and MATLAB Compiler&trade;.
- Private project — The CI integration does not automatically license any products for you.
* Public project — The CI integration for MATLAB automatically licenses all products for you, except for transformation products, such as MATLAB Coder&trade; and MATLAB Compiler&trade;.
* Private project — The CI integration does not automatically license any products for you.

To license products that are not automatically licensed, 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. Batch licensing tokens are strings that enable MATLAB to start in noninteractive environments.

<br>

## See Also
- [Continuous Integration (CI) configuration examples for MATLAB](https://github.com/mathworks/ci-configuration-examples)
- [Continuous Integration with MATLAB and Simulink<sup>&reg;</sup>](https://www.mathworks.com/solutions/continuous-integration.html)

* [Continuous Integration (CI) configuration examples for MATLAB](https://github.com/mathworks/ci-configuration-examples)
* [Continuous Integration with MATLAB and Simulink<sup>&reg;</sup>](https://www.mathworks.com/solutions/continuous-integration.html)

<br>

## Feedback and Support

If you encounter a product licensing issue, consider requesting a MATLAB batch licensing token to use in your workflow. For more information, see [Licensing](#licensing).

If you have an enhancement request or other feedback, create an issue on the [Issues](https://github.com/mathworks/advanced-ci-configuration-examples/issues) page.
Expand Down