Make GIBBON be a proper/official integrated MATLAB toolbox

[Kevin-Mattheus-Moerman]

I.e. work on toolbox packaging so rather than the custom install script (or complementary to it) work to make GIBBON an toolbox integrated as shown here:
https://uk.mathworks.com/help/matlab/matlab_prog/create-and-share-custom-matlab-toolboxes.html

[vijayiyer05]

Relevant to this issue: the transition to package management is now described in the R2026b prerelease notes.

[martinherrerias]

I've created a matlab.toml and put in in the issue branch.
Also created a test repo with extended notes: https://github.com/martinherrerias/matlab-packaging-test

From what I understand, the matlab.toml is a great step forward from the messy *.prj-based toolbox packaging, but I don't see what advantages it might have (from a CI/CD perspective):

• matlab.toml metadata is ignored by both GitHub-FileExchange integration, and also by mpminstall¹
• It seems still a bit "raw" (not all project features seem supported?)²
• It only works on R2026b (prerelease), which no-one is using, and does not yet run on GitHub actions

We could merge the TOML file into the main branch (I guess it doesn't hurt to have it there), or just worry about it when the promised mpminstall-FileExchange integration is actually working.

@vijayiyer05, are we missing something?

Footnotes

1. Placed a feature request 08888439 ↩

2. Placed a bug report for this 08886969 ↩

[martinherrerias]

Copying the reply to my feature request for a "unified" source of package metadata (08888439):

(1) matlab.toml and mpminstall
mpminstall currently depends on "resources/mpackage.json" as its package definition file. This is a documented behavior; the function reads and stores metadata from :mpackage.json" at install time. "matlab.toml" is not yet a supported input for "mpminstall".

As a workaround, I recommend retaining "resources/mpackage.json" alongside "matlab.toml" for mpm compatibility. The two files can coexist without conflict. More information regarding "mpminstall" can be found in the documentation:
https://www.mathworks.com/help/matlab/ref/mpminstall.html [mathworks.com]

(2) matlab.toml with Toolbox Packaging APIs

Your approach is correct and is the supported path for building ".mltbx" files from "matlab.toml".

(3) GitHub–File Exchange Integration and Metadata
You are correct that the GitHub–File Exchange integration does not currently read matlab.toml or mpackage.json from your repository to populate the File Exchange listing. The integration reads metadata from the GitHub API itself (repository name, description, release tag, release notes). However, there is a practical path to reduce manual effort: if you attach a .mltbx file as an asset to your GitHub release, File Exchange will automatically extract metadata embedded inside the .mltbx including title, version, MATLAB release compatibility range, required products, and UUID. This is currently the most automated route available for keeping your File Exchange listing up to date without manual web UI entry for those fields.

(4) Automating .mltbx Builds on GitHub Actions

To automate creation of the .mltbx file for each release, you can use the official MATLAB GitHub Action, matlab-actions/run-build, to run a MATLAB build script or build task that calls matlab.addons.toolbox.packageToolbox. The generated.mltbx can then be uploaded as a GitHub release asset using a standard GitHub Actions release step.

You may refer to the following documentation for the Continuous Integration reference:
https://www.mathworks.com/help/matlab/matlab_prog/continuous-integration-with-matlab-on-ci-platforms.html [mathworks.com]

Once R2026b is running on GitHub actions we could set up a pipeline to build the *.mltbx file on CI and add it to each release.

[vijayiyer05]

Glad to see a smooth first use of the MATLAB.toml format and thank you for sharing where you've had success (creating MLTBX) and where you've been hindered (CI & command-line install).

My instinct now would be to break up this issue (one way or another) into what makes sense before R2026b and what makes sense this summer with the R2026b prerelease. I'm consulting colleagues to think on what could be a good place to "declare victory" in this R2026b prerelease era.

[bpancras]

Hi @Kevin-Mattheus-Moerman and @martinherrerias,
I looked at your 202-toolbox-packaging branch, here is some of my initial thoughts:

1. matlab.toml contains the metadata that describes your MATLAB Project or your authoring environment. This should be contrasted with the execution environment your users need to correctly execution your code. Often the users execution environment is a subset of your authoring environment.
2. installGibbon.m located at repo root contains logic for setting up the execution environment. When you double click matlab.toml it executes this file and add the required source code in MATLAB path. My first glance at installGibbon.m indicates the following
   - lib, data/temp` and its sub folders are added to MATLAB Path
   - Add FEMBio to path
   - Check required MATLAB Products
   - Unzip compressed data
   - Build help/ documentation
3. When you double clicking matlab.toml MATLAB sets-up your authoring environment by starting the Project. The Project tab also contains a stop Project button, that lets you tearing down your authoring environment and retuning MATLAB to its pristine state. Your installGibbbon.m and uninstallGibbon.m does this in some sense. I recommend you to use the Project Folder- Path configuration in Project to set-up and tear down your authoring environment.
4. I'm not sure if uzipping compressed data and building documentation should be performed at Project start. You can explore build tool tasks for accomplishing some of these task. Adopting buildtool can also help you transit to CI workflows seamlessly.

I don't understand the nuances of FEMBio yet, I need to dig a little more, I'll come back to this issue once I have some clarity. Let me know your reaction to these thoughts.

[martinherrerias]

Hi @bpancras, thanks for the comments, we had talked about some of these things internally, but never formalized them as issues. I hope #216, #217, #218 address your concerns?

It wasn't clear to me how the difference between authoring vs development environments would show up in the TOML file. I realize now there's an additional folders.path field in the [[package]] key reserved for end-user paths. Let me know if my description in #216 is not accurate.