Shipping a MATLAB Runtime Application (MATLAB Runtime Server)

MATLAB Runtime Server

Installing and Running the Application

This section discusses the installers provided on PC and UNIX platforms, tips for building an installer yourself for PC applications, and other special considerations for PC applications.

Automatically Built Installer on PC

If you use package to organize your files for shipping, then it automatically builds an installer for your end user. To install the application in a given directory, copy setup.exe into that directory and execute setup.exe. This creates a batch file whose name is the application name that you specified when you first used package. To launch the application, type the application name.

Sample Installer on UNIX

When you use package to organize your files for shipping, your user.files listing includes a file called user.install. This file is a sample installer for your end users. If your application has any special installation or execution requirements, then you might need to modify user.install accordingly. When your end users want to install and run your application, they should follow these instructions:

Unpackage the application with these commands.

```
mkdir prog
cd prog
tar -xvf ../app.tar
```

Run the installer program with this command.

```
user.install `/bin/pwd`
```

Run the application with this command.

```
user.app
```

user.app requires that DISPLAY be set. Alternatively, pass the DISPLAY value as an argument.

The sample files user.install and user.app are in toolbox/runtime/oem. For more details, see the README file in toolbox/runtime/oem.

Manually Building an Installer on PC

If you copied and organized your files manually, then you need to create an installer for your application. The key consideration for the installation process is that the Runtime Server should be able to locate the application files when it is launched. To be certain of this:

Make sure that your application directories are on the runtime path, as discussed in the section Creating the Path Definition Function.
Make sure that the Runtime Server can find matlabrt.p and pathdefrt.p. These startup files need to be in the toolbox\local directory or the current directory.

Associating Files with the MATLAB Runtime Server on PC

In addition to installing the files, the installer software can associate the application files with the Runtime Server executable. This allows the user to launch the application (without explicitly launching the Runtime Server) by clicking on an application file icon or typing the application name.

To create custom icons for the application files, the installer should register the file extensions of all related files to open with the Runtime Server. Clicking on any file will then launch the Runtime Server and start the application. You might also want the installer to create a shortcut to launch the application.

Registering MATLAB as an Automation Server on PC

If you are shipping a MATLAB runtime engine application for PC platforms, then the Runtime Server needs to be registered in the Microsoft Windows Registry on the user's computer as an Automation Server. The Runtime Server will register itself with this designation each time it is run with the /Automation flag.

To register the Runtime Server, your installer software should run the Runtime Server executable once as the last step of the installation. Because the Runtime Server cannot be launched through the Engine API commands until it is registered, the installer needs to launch the Runtime Server executable explicitly with the /Automation flag.

During this initial run, the application's matlabrt.p file needs to provide a mechanism for the Runtime Server to quit. You can build in this facility by making one change to the matlabrt file, and by installing an extra file in the toolbox\local directory.

Follow these steps:

Add the following lines at the beginning of the matlabrt.m file, right after the function header.

if exist('register.txt') == 2
  delete('register.txt');
  quit;
end

This causes the Runtime Server to look on the path for a file called register.txt. If the file exists, the Runtime Server deletes the file and quits. This brief execution is enough for the Runtime Server to register itself as an Automation server.

Create the file register.txt, or instruct the installer software to create it. It should be installed in the toolbox\local directory (along with matlabrt.p). It will be deleted when the installer initially runs the Runtime Server, so the contents of the file are not important.

Manually Packaging Files for Shipping (PC) Final Testing