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.
Thoughts?Do you have any experiences to share that can help avoid packaging pitfalls? If so, let me know about it in the comments!
Get the MATLAB code Published with MATLAB® R2017a
2 CommentsOldest to Newest
I haven’t used toolboxes before though we have organized our common library of functions as a package. What are the primary use cases of toolboxes and where can I learn more about the basics?
Toolboxes are great! They help you package and distribute a set of related code into one sharable file. They help manage installation and path updates required for the code and integrate into our add-on manager. probably the best places to start are Amy’s first post on packaging toolboxes and the documentation. Have fun and I hope it solves some problems for you!