MATLAB Runtime Server

Compiling the Application (GUI)

In order for the application to work with the MATLAB Runtime Server, you must compile the application M-files into runtime P-files. A runtime P-file differs from a standard P-file in that the former is stamped with the same password that you used when executing rtsetup.

This section discusses:

• The compilation process in general
• How to compile the application with one command
• How to compile selected M-files
• How to remove compiled files

Overview of Compilation

A shipping runtime application contains compiled versions of these files:

• Files you write for your application
• M-files from toolbox\matlab that your application uses
• matlabrt.m and pathdefrt.m

Note    Runtime P-files can be created only by a stamped commercial copy of MATLAB. Also, the Runtime Server inherits the password of its commercial MATLAB parent and can execute only those runtime P-files having that same password. See Password Consistency Rules to ensure compatibility. (Commercial MATLAB can execute both standard and runtime P-files.)

Note    Purchase of the MATLAB Runtime Server does not imply a license to compile and ship functions from MATLAB add-on products. Please contact The MathWorks for information on shipping components of add-on products.

The easiest way to compile the application is to use the buildp function. This function determines which files to compile and compiles them. Thus you do not have to compile each file individually. To learn about this approach, see Compiling the Application with One Command below.

Alternatively, you can use depfun in conjunction with pcode. To learn about this approach, see Compiling Selected M-Files.

Note    When compiling your application and creating your deployment structure, you must use the -inplace flag with pcode or the default 'develStruct' option of buildp to have the P-files mirror the directory structure of the M-files.

Tips for Compiling.   Here are a few tips to keep in mind when compiling M-files:

• Before compiling files or seeking dependencies, you should use cleanp to remove all files with a .p extension on the MATLAB path. This function also removes .p files in the current directory.
• If you do not remove existing P-files, then buildp and pcode overwrite them if necessary.
• To register the changes after creating or deleting P-files, you should execute a rehash toolboxreset command or restart MATLAB. If you use cleanp or buildp, then you do not need to issue this command since cleanp and buildp do it for you.
• You might want to save the output of buildp or depfun in a MAT-file for later use. For example, before packaging your application to ship to users, you need a list of all files that the application depends on.

Compiling the Application with One Command

The buildp function creates P-code for an entire runtime application once you specify the key files in the application. Typically, you specify only the top-level file, though you might need to specify a small number of other files, as mentioned in the troubleshooting section below. The buildp function determines which files to compile, compiles them into runtime P-files, and places the runtime-ready files alongside their uncompiled counterparts.

The buildp command below creates P-code for a runtime application whose top-level file is matlabrt.m.

• log = buildp({'matlabrt'});
  

The output log is a string containing the name of a file that details the various phases of execution of buildp.

Troubleshooting After Using buildp.   For some applications, one call to buildp creates the entire set of runtime-ready files. However, for some applications, you might need to use buildp more than once to determine the best input list for buildp. Check the the log file (whose filename is the output string log) and/or the output for information and diagnostics. Here are some troubleshooting tips in case buildp either fails, indicates a potential problem, or gives incomplete results:

• If your application uses toolbar items from the MATLAB default figure window, then include 'FigureToolBar.fig' in the first input argument of buildp.
• If your application uses menu items from the MATLAB default figure window, then include 'FigureMenuBar.fig' in the first input argument of buildp.
• If your application uses GUI elements and creates .fig files, then include those .fig files in the first input argument of buildp.
• If buildp cannot parse a file or cannot resolve a symbol, then its results might be incomplete. Check your files for syntax errors, misspelled variable or function names, and other errors. Then invoke buildp again.
• If your application (including functions on which the application depends) uses an evaluation function (eval, evalc, evalin, or feval), then buildp cannot determine whether the evaluation string contains the name of a function that needs to be compiled. buildp reports instances of evaluation functions. You should check each instance manually and decide whether any additional files should be compiled. Then invoke buildp again and include those additional files in the first input argument.

• For example, if you use an evaluation command to execute either comp1.m or comp2.m, then you can modify a buildp command like

  log = buildp({'matlabrt'});

  so that it becomes

  log = buildp({'matlabrt','comp1','comp2'});

  For additional suggestions for dealing with evaluation functions, see Analyzing Functions Called by eval.

Compiling Selected M-Files

To compile selected M-files into runtime P-files, use the pcode command with the runtime flag. The runtime flag tells MATLAB to create a runtime P-file, instead of the standard P-file. Other flags and options can control which files are compiled and where the runtime P-files are placed, as explained below.

Use the -inplace flag with the pcode command, as follows. For the file myfile.m, type

• pcode myfile -inplace -runtime
  

To compile the entire application, apply depfun to the top-level M-file (matlabrt.m) and then apply pcode to the output. This is an alternative to using the buildp command as explained earlier. Here, the purpose of using depfun is to determine which M-files to compile. The commands are below.

• list = depfun('matlabrt');
  pcode(list{:},'-inplace','-runtime')
  

Troubleshooting After Using pcode.   If your application uses toolbar or menu items from the MATLAB default figure window, then you need to include 'FigureMenuBar.fig' and 'FigureToolBar.fig' in your input to depfun. If your application uses GUI elements and creates .fig files, then you should include those .fig files in your input to depfun as well.

Also note that there are some circumstances in which depfun provides an incomplete list. For details, see Analyzing Functions Called by eval.

Removing P-Files

To remove all files with a .p extension on the path and in the current directory, type

• cleanp
  

Caution    cleanp looks only at names, not contents, of files. Use caution if you have files other than MATLAB P-files that use a .p filename extension.

Organizing Files and Managing Startup Tasks (GUI)

Testing While Emulating the Runtime Server (GUI)