MATLAB Compiler on OS X

The MathWorks has a great product for MATLAB® called MATLAB® Compiler™. It wraps up just about any program written MATLAB in an executable so others can run it without needing MATLAB or any kind of license. It's an expensive tool, but as a consultant who builds many math-heavy applications for clients who want to "just use" the tools I've created, it's been a big payoff for me.

However, when it comes to building for OS X, there are some bugs and quirks. I couldn't find any help on this online, so let's blast through them here. Note that this is all work for the developer; the user of the "compiled" application doesn't have to do anything. For the user, it will just work.

Getting started with Compiler is super easy (we'll show R2014a here). If the MATLAB program is called hst.m, then just start the Compiler application, enter hst.m as the main file. Add an application name and installer name too.

Screenshot 2015-02-28 12.26.00

On Windows, you'd just click "Package" and be done. It would generate an installer .exe file which you could give to anyone running Windows (again, they don't need MATLAB to run it). Then you could spend the afternoon playing ping pong.

On OS X, you'll have to skip ping pong. There's more to do.

The DMG

First, the directory containing hst (likely the working directory) needs to be on a path without any spaces (e.g. /Users/Me/Dev/MATLAB instead of /Users/My Name/My Dev Work/MATLAB). Second, when you name the application, you can't use spaces in the name. In fact, spaces in path names are the main problem throughout, and they're surprisingly hard to avoid. (Note to The MathWorks: It's 2015. My paths have spaces. Every other code-related tool I use is fine with this.)

Ok, now you can click "Package". It will build hst_installer_osx.app under ./hst_installer_osx/for_redistribution/hst_installer_osx.app.

Screenshot 2015-02-28 12.28.09

If all went perfectly, running this app would install the generated program in Applications. However, there are many reasons this might not work. You also can't run the installer from a path with spaces. Further, you can't easily send a .app file to someone. We can take care of both of these at once by creating a DMG, the standard packaging that most installers use. It's pretty easy.

Under Applications and Other, you'll find Disk Utility. Open this up.

Screenshot 2015-02-28 10.58.57

Create a new image, choose a file name with no spaces, and also choose a disk name with no spaces.

Screenshot 2015-02-28 11.01.28
No spaces in the file name or image name!

 

This will create the DMG file wherever you specified (the desktop by default), and it will also "mount" the DMG, so the DMG is like a new drive attached to the computer.

Screenshot 2015-02-28 11.01.59

Open up the mounted DMG and drag in the installer app from wherever it was generated.

Screenshot 2015-02-28 11.02.21

Almost done. Unmount the drive (drag the mounted drive icon to the trash or right-click on it and select "Eject").

Go back to the Disk Utility.

Screenshot 2015-02-28 11.03.01

Select the DMG file and click "Convert" up top. This will "seal up" the DMG, making it as small as possible. It's kind of like creating a zip.

Screenshot 2015-02-28 11.03.08

The DMG is now ready to distribute to the target users. When they run it, it will download some things from The MathWorks (runtime libraries and such), install the tool in Applications, and be ready to launch. It will act just like it did in MATLAB.

Screenshot 2015-02-28 11.05.52

The process of building and creating a DMG could probably be wrapped up in an AppleScript or a MATLAB script that uses the system command to manipulate the DMG, but I have not tried to automate this. Is this interesting? Message me to let me know.

Deployment

Building these applications is tremendously useful. A single person can create a useful tool in MATLAB and give it out to anyone. For instance, I've created tools to help me in designing a satellite. At some point, one of the guys from mission control saw me working with it at my desk. He said, "Hey, this would be useful in operations. What would it take for us to put this on all the computers in mission control?" Virtually nothing it turns out; I loaded up Compiler and generated an executable for him, and he had IT install it. No MATLAB licenses were necessary for the operators, and the whole process was very quick compared to the cost of traditional methods of developing these types of stand-alone applications. So, even when there are some hoops to jump through, Compiler is still a great tool in my workflow, and it's paid off many, many times over in what it allows me and others to do.

That said, here are the last few things you'll need to know for OS X. These are the things that keep tools generated with Compiler from being fully professional; this is why I would never release a commercial program that was built with Compiler.

When you install the app, it will download a big runtime library from The MathWorks. On Windows, this only happens the first time you install an app generated with Compiler (for a given version of Compiler). On OS X, this download will happen every time you install or re-install an application from Compiler. Further, the download is very slow, and yet it won't prevent your computer from going to sleep. If your computer sleeps during installation, the download will fail, and you'll have to start the installation over again — a massive pain.

Screenshot 2015-02-28 11.10.19
Don't let it sleep! Turn off sleep or just keep using the computer with this minimized.

 

Second, it might not be clear how to run the application. It's under /Applications/<name of project>/application/<name of app>.app.

Third, and perhaps worst, is that the generated application will have a help menu. When I first saw this, I thought "Great! How can I add help?" It turns out that you can't add help. In fact, if the user clicks on the help menu, the program will become unresponsive and must be killed with Apple Menu > Force Quit....

Screenshot 2015-02-28 12.14.20

Alas, the Windows version is far superior. The OS X version is, like it is for many MathWorks products, an afterthought and full of bugs. The bugs are navigable, however, so I hope this article helps folks build their applications reliably when their target users are using OS X, which from this engineer's perspective is gaining far more widespread use in engineering.

Are you building for OS X? What other problems have you had? Message me if there's something I should add here.

Fine Print

I'm using MATLAB Compiler with MATLAB R2014a for this example. The MathWorks is always updating its toolboxes, and Compiler seems to have been receiving special attention lately, and so it's changing quickly from version to version.

Leave a Reply

Your email address will not be published. Required fields are marked *