Packaging Pitfalls

Posted by Andy Campbell, August 21, 2017

2 views (last 30 days) | 0 Likes | 5 comments

Hello readers, today we have another post from Amy, who is here to share more of her valuable experience deploying toolboxes. Take note of some of these tips after you have thoroughly enjoyed any eclipse observations you have been lucky enough to witness this time around. Just like looking at an eclipse directly is something you want to avoid, so are these packaging anti-patterns. Take it away Amy!

What are some common pitfalls when packaging a toolbox?

In one of my previous posts, I described how to set up your development environment in MATLAB when developing and packaging a MATLAB toolbox. In this post, I'll share ways to avoid common pitfalls which can cause the toolbox packaging process to fail.

Toolbox project file contains absolute paths to files

It's important to understand how the project file (.prj) handles paths to ensure that they function correctly irrespective of the absolute sandbox path. In my other post, I recommend that the toolbox content sits below the folder containing the project file (i.e. the "project root folder") in the folder hierarchy. In this case, the project file stores paths relative to the project root folder. When the project content is not below the project root folder, including the case when the project content is directly *in* the project root folder, the project file stores absolute paths. If someone attempts to use such a project file in another location the file fails to load.

Sandbox code not on the MATLAB path

Make sure that the sandbox code is always on the MATLAB path when packaging. Prior to R2016a, if the packaged folders are not on your path when packaging, they won't be added to the user path when your user installs the package, even though the content is installed. Consequently, users won't be able to access the toolbox functionality without manually adding the toolbox folder to the path. From R2016a, you can select which toolbox folders are added to the user's MATLAB path when they install a toolbox. By default, the list includes any of the toolbox folders that are on your path when you package the toolbox. You can exclude folders from being added to the user's path by clearing them from the list. It's useful to write scripts for adding and removing sandbox code, i.e. addsandbox.m and rmsandbox.m, from the MATLAB path. Always make sure to run addsandbox.m when packaging and rmsandbox.m before testing the packaged content.

Accidentally resetting your GUID

Each project file (.prj) is associated with a unique identifier or GUID. MATLAB uses this identifier to manage the toolbox upgrade and installation process. When a new version of a toolbox is installed, MATLAB removes older versions of the toolbox packaged using the same project file. Essentially these are .mltbx files that can be identified using the same GUID. However, if a new version is packaged using a new or different project file, MATLAB will recognise these as two separate toolboxes even though they might have the same name.

Conflicting external dependencies

MATLAB checks and identifies external files required for your toolbox code to run during the packaging process. You can choose to exclude any files you don't want. Again, the project file (.prj) stores the absolute path of these external files when they are not below the project root folder. If someone tries to repackage the toolbox in another location using the same project file, but doesn't have the same environment set up, the packaging process will fail. For ease of portability I recommend excluding external files from your packaged toolbox. You can remove these external dependencies from your MATLAB path when packaging so that MATLAB doesn't identify them. When external dependencies are excluded from the packaged toolbox, you'll want to check that the users have installed these prior to running your toolbox code. If the external dependencies are MATLAB toolboxes, you can use the matlab.addons.toolbox.installToolboxes API to query information about installed toolboxes from R2016a. Otherwise, if a toolbox contains a Contents.m file, users can query version information of the toolbox using the ver command.