MatBox: CI Tools for MATLAB Toolbox Development

---

MatBox is a streamlined solution for managing MATLAB toolbox development: automate code checks, dependency management, cleaning, packaging, and continuous integration.

---

🚀 Features

• Automated Dependency Management: Use a requirements.txt for easy installation/configuration.
• Continuous Integration: Ready-to-use GitHub Actions and workflow templates for code analysis and unit testing.
• Effortless Packaging: Bundle your toolbox with a simple MLToolbox.json file.

---

⚡ Quickstart

1. New Projects

• Create a repository using the MATLAB Toolbox Template.
• (Optional) Add dependencies in a requirements.txt (see below).
• Customize setup.m (template here).
• Adjust workflow files in .github/workflows if needed.
• Add or override CI functions in the tools/ directory.

2. Adding to Existing Projects

Note: Direct documentation for retrofitting MatBox to existing repositories is in progress.
See openMINDS-MATLAB-UI for a practical example.

Minimal steps:

• Add MatBox as a dependency (see matbox-actions/install-matbox).
• Add/adjust requirements.txt, setup.m, and .github/workflows as above.
• Place custom tasks (optional) in a tools/ folder.

---

📦 Requirements & Installation

• MATLAB R2023a or later is recommended for toolbox packaging (other features may work with older versions).
• To install dependencies listed in your requirements.txt:

  matbox.installRequirements(pwd)

• Example requirements.txt:

  https://github.com/openMetadataInitiative/openMINDS_MATLAB
  https://github.com/ehennestad/StructEditor
  fex://66235-widgets-toolbox-compatibility-support/1.3.330
  fex://83328-widgets-toolbox-matlab-app-designer-components
  

---

🧑‍💻 Basic Usage

• Run tests:

  matbox.tasks.testToolbox(pwd)

• Package your toolbox:

  [newVersion, mltbxPath] = matbox.tasks.packageToolbox(pwd, 'build')

---

🔧 Customizing Tasks

MatBox lets you override or extend its default behavior by adding custom task functions to your repository’s tools/ directory. This is especially useful if you want to:

• Run additional CI steps (like linting, style checks, or artifact generation)
• Customize how tests or packaging are run for your toolbox
• Add project-specific setup or teardown logic

How it Works

When a workflow or CI job calls a MatBox task (like matbox.tasks.testToolbox), it will check if a function with the same name exists in your tools/ directory and use that version instead of the built-in one.

For example:
If you create a tools/testToolbox.m file, your version will run instead of the default MatBox test task.

Example: Custom Test Task

% File: tools/testToolbox.m

function testToolbox(varargin)
    % Project-specific test setup (optional)
    disp('Running custom project tests...');
    % Call the core MatBox test task (optional)
    matbox.tasks.testToolbox(pwd, varargin{:});
    % Add any extra steps here
end

Other Common Task Overrides

You can override any task by creating a function with the same name as the task in your tools/ directory, e.g.:

• testToolbox.m  →  Custom test runner
• packageToolbox.m  →  Custom packaging logic
• codecheckToolbox.m  →  Custom code analysis

Best Practices

• Call the original MatBox task from your override if you want to extend (not replace) its behavior.
• Use the tools/ directory to keep custom CI logic organized and version-controlled.
• Document your custom tasks for future contributors!

For practical examples, see the openMINDS-MATLAB-UI repository.

---

🏁 Example Repositories

• dropbox-sdk-matlab
• openMINDS-MATLAB-UI

---

🛠 FAQ / Troubleshooting

Q: Can I use MatBox with an existing non-template repo?
A: Yes, with some manual setup; see the example repo.

Q: Where do I put custom CI or utility functions?
A: In the tools/ directory of your project.

Q: How do I run tests or package my toolbox?
A: See "Basic Usage" above.

---

📝 License

This project is available under the MIT License. See LICENSE.

---

See also:

• MatBox Actions (GitHub Actions)
• MATLAB Toolbox Template