Skip to content

README.md

Latest commit

 

History

History
160 lines (111 loc) · 8.7 KB

README.md

File metadata and controls

160 lines (111 loc) · 8.7 KB
Dropbox-API-Client-logo

MatBox: CI Tools for MATLAB Toolbox Development

Version Number View MatBox on File Exchange MATLAB Tests codecov MATLAB Code Issues Maintenance Release

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

🛠 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: