MatlabProjectTemplate

Travis Build Status CircleCI Build Status Azure Build Status View MatlabProjectTemplate on File Exchange

MatlabProjectTemplate (“MPT”) is a template repo for creating Matlab library and application projects. It defines a “standard” project structure that should be suitable for many projects, including those intended for redistribution / open source. You can think of it as sort of a community-supported Reference Implementation for Matlab packages.

It is suitable for both libraries and applications, and includes coding and organizational conventions that make it safe to use this project’s code in a Matlab environment that uses code from other projects, too. MPT follows Janklab’s philosophy of treating Matlab as a serious programming language, instead of an overgrown interactive graphing calculator.

This template is based on the author’s 20+ years of professionally building Matlab and other software, so it should be pretty good.

Features

MatlabProjectTemplate supports the following features. You don’t have to use any of them; you can just ignore the ones you don’t care about. But they’re there if you need them!

  • Collaboration between multiple developers
  • Building Matlab Toolboxes
  • Matlab Continuous Integration and unit tests
  • Distribution as both plain zip files and Matlab Toolbox .mltbx files
  • Using (“vendoring”) third-party Java JAR and Matlab libraries
  • Writing nice documentation
  • Custom Java code
  • Library initialization
  • Automatic library initialization
  • Logging, in an SLF4M/SLF4J/Log4j-compatible manner

Usage

To create a new project from this template, go to its repo on GitHub and create a new repo by clicking the green “Use this template” button.

NOTE: Don’t “fork” or “clone” the MatlabProjectTemplate repo. That will leave your project’s Git repo set up wrong! Do the “Use this template” thing.

Then:

  • Add a license file!
  • Edit the variables project_settings.m.
  • Run init_project_from_template.m in Matlab.
  • Edit .editorconfig to reflect your preferred code style.
  • Edit <myproject>.prj.in and put in all your contact and descriptive info and other stuff.

And then:

  • Put your main Matlab source code in Mcode/.
  • Put your example scripts in examples/.
  • Edit the files in doc-project to reflect your plans.
  • Hack away!

When you’re developing code for your project, you should add the dev-kit/ directory to your Matlab path.

See the User Guide for more information and details.

Requirements

Just Matlab, for most of it.

Some features (some doc building/previewing, and custom Java code builds) only work on Mac and Linux. But don’t worry! If you’re on Windows, you can install Windows Subsystem for Linux and use that.

See Using on Windows for details.

Unit tests

You should write unit tests for your project! Use the Matlab Unit Test Framework and put your tests in Mcode/+<myproject>/+test. Run them with make test in the shell or with dev-kit/launchtests.m in Matlab.

License

MatlabProjectTemplate is multi-licensed under all of: MIT License, BSD 2-Clause License, Apache License, and GPLv3. You can use it in any project with a license compatible with any of those licenses. This includes commercial and proprietary software.

If you have a licensing scenario which is not covered by the above (and jeez, what are you doing that would require that?), just contact me, and I’ll probably add support for it. My intention is that everybody can use MatlabProjectTemplate.

More info

About MatlabProjectTemplate

MatlabProjectTemplate was written by Andrew Janke. The project has a web site and you can find a repo on GitHub. You can get support, or even contribute to the project, there. Bug reports, feature requests, and other feedback are welcome.

MatlabProjectTemplate is part of the Janklab suite of libraries for Matlab.