Include and Access Files in Packaged Applications

In addition to MATLAB^® script files, you can add other types of files to deployable archives such as data files, DLLs, and files from other programming languages. Access the additional files from your deployed code by using the which function or referencing the file location relative to the deployable archive root ctfroot.

For more information about deployable archives, see About Deployable Archives.

Include Files in Deployable Archive

MATLAB Compiler™ uses a dependency analysis function to determine the list of necessary files to include in the generated package. For details, see Dependency Analysis Using MATLAB Compiler.

You can include additional files in the deployable archive using the -a flag with the mcc command or the 'AdditionalFiles' option using a compiler.build function, such as compiler.build.standaloneApplication.

Alternatively, you can add files to the Files installed for your end user section in a deploytool app so that they appear in the same directory as the executable after installation.

Explicitly Include MATLAB Data Files Using %#function Pragma

The compiler excludes MATLAB data files (MAT-files) from dependency analysis by default. You can include data files by adding them manually.

If you want the compiler to explicitly inspect data within a MAT-file, specify the %#function pragma when writing your MATLAB code.

For example, if you want to include a dependency on the ClassificationSVM class loaded from a MAT-file, use the %#function pragma.

function foo 
    %#function ClassificationSVM 
        load('svm-classifier.mat');
        num_dimensions = size(svm_model.PredictorNames, 2);
end %function foo

Include MEX-Files, DLLs, or Shared Libraries

When you compile MATLAB functions containing MEX-files, ensure that the dependency analyzer can find them. In particular, note that:

Since the dependency analyzer cannot examine MEX-files, DLLs, or shared libraries to determine their dependencies, explicitly include all executable files these files require.
If you have any doubts that the dependency analyzer can find a MATLAB function called by a MEX-file, DLL, or shared library, then manually include that function.
Not all functions are compatible with the compiler. Check the file mccExcludedFiles.log after your build completes. This file lists all functions called from your application that you cannot deploy.

Access Files from Deployed Functions

To access files from your deployed MATLAB code, check if the code is running in deployed mode using isdeployed. Then, locate the file either by using the which function or by specifying the file location relative to ctfroot.

Use `which` function

The simplest way to obtain the path to a file is to locate the file by using the which function.

if isdeployed
    locate_externapp = which('extern_app.exe');
end

The which function returns the path to the file extern_app.exe if it is located within the deployable archive.

Specify File Location in `ctfroot`

When you include files that are in a folder other than the current MATLAB working folder, the partial file path is preserved in the deployable archive relative to ctfroot.

Files within the current MATLAB working folder or subfolders retain the relative path from the current folder to the file.
For example, if the folder open in MATLAB during packaging is D:\Documents\Work\MyProj, then the file D:\Documents\Work\MyProj\exfiles\data1.mat will be located at ctfroot\mfilename\exfiles\data1.mat in the deployable archive, where mfilename is the name of the main MATLAB script file.
Files outside of the current folder retain the full folder structure from the root of the disk drive.
For example, the file C:\Users\mwuser\Documents\External\externdata\extern_app.exe will be located at ctfroot\Users\mwuser\Documents\External\externdata\extern_app.exe in the deployable archive.

Use the fullfile function to ensure that file paths use the correct file separators for your system.

if isdeployed
    locate_data1 = fullfile(ctfroot,'exfiles','data1.mat'));
    locate_data2 = fullfile(ctfroot,'Users','mwuser','Documents',...
        'External','externdata','extern_app.exe'));
end

Example Processing MATLAB Data for Deployed Applications

This example shows how to include data files in a packaged application and use the load and save functions to manipulate MATLAB data.

Navigate to your work folder in MATLAB. For this example, the work folder is C:\Users\mwuser\Documents\Work\exfiles.
Copy the Data_Handling and externdata folders that ship with MATLAB to your work folder.
```
copyfile(fullfile(matlabroot,'extern','examples','compiler','Data_Handling'),'Data_Handling');
copyfile(fullfile(matlabroot,'extern','examples','compiler','externdata'),'externdata');
```
At the MATLAB command prompt, navigate into the new Data_Handling folder in your work folder.

Examine ex_loadsave.m.

The ex_loadsave script loads three MATLAB data files, each located in a different folder:

user_data.mat — In the current folder
userdata\extra_data.mat — In a subfolder of the current folder
..\externdata\extern_data.mat — Outside of the current folder

ex_loadsave.m

function ex_loadsave
% This example shows how to work with the "load/save" functions
% on data files in deployed mode. This example contains three
% source data files.
%    user_data.mat 
%    userdata/extra_data.mat 
%    ../externdata/extern_data.mat
%
% Compile this example with mcc command: 
%     mcc -m ex_loadsave.m -a 'user_data.mat'
%         -a './userdata/extra_data.mat'
%         -a '../externdata/extern_data.mat'
%
% In this example, the output data file is written to the path:
%	output/saved_data.mat
% relative to the application's run time current working directory.
% When writing data files to local disk, do not save any files under $ctfroot,
% as $ctfroot may be deleted and/or refreshed for each application run.
%
%==== load data file =============================
if isdeployed
    % In deployed mode, all files in or under the main file's directory
    % may be loaded by full path, by path relative to ctfroot, or by
    % filename only, since their directories are on the MATLAB path.
    % Here we load 'user_data.mat' by full path.
    LOADFILENAME1=which(fullfile(ctfroot,mfilename,'user_data.mat'));    
    % These alternate methods also work:
    % LOADFILENAME1=which(fullfile(mfilename,'user_data.mat'));    
    % LOADFILENAME1=which(fullfile('user_data.mat'));

    % Here we load 'extra_data.mat' by relative path:
    LOADFILENAME2=which(fullfile('userdata','extra_data.mat'));
    % These alternate methods also work:
    % LOADFILENAME2=which(fullfile(ctfroot,'userdata','extra_data.mat'));
    % LOADFILENAME2=which(fullfile('extra_data.mat'));

    % For a data file external to the main MATLAB file's directory tree,
    % its full compile time path is appended to $ctfroot, so it is
    % best to simply load it by filename (since it is on the path):
    LOADFILENAME3=which(fullfile('extern_data.mat'));
else
    %running the code in MATLAB
    LOADFILENAME1=fullfile(pwd,'user_data.mat');
    LOADFILENAME2=fullfile(pwd,'userdata','extra_data.mat');
    LOADFILENAME3=fullfile(pwd,'..','externdata','extern_data.mat');
end

% Load the data file from current working directory
disp(['Load A from : ',LOADFILENAME1]);
load(LOADFILENAME1,'data1');
disp('A= ');
disp(data1);

% Load the data file from subdirectory
disp(['Load B from : ',LOADFILENAME2]);
load(LOADFILENAME2,'data2');
disp('B= ');
disp(data2);

% Load extern data outside of current working directory
disp(['Load extern data from : ',LOADFILENAME3]);
load(LOADFILENAME3);
disp('ext_data= ');
disp(ext_data);

%==== multiply two data matrices together ==============
result = data1*data2;
disp('A * B = ');
disp(result);

%==== save the new data to a new file ===========
SAVEPATH=strcat(pwd,filesep,'output');
if ( ~isdir(SAVEPATH))
    mkdir(SAVEPATH);
end
SAVEFILENAME=strcat(SAVEPATH,filesep,'saved_data.mat');
disp(['Save the A * B result to : ',SAVEFILENAME]);
save(SAVEFILENAME, 'result');

Create a cell array that lists the data files.

datafiles = {'user_data.mat','./userdata/extra_data.mat','../externdata/extern_data.mat'};

Compile ex_loadsave.m using the compiler.build.standaloneApplication function.

compiler.build.standaloneApplication('ex_loadsave.m','AdditionalFiles',datafiles)

Run the compiled application.

!ex_loadsavestandaloneApplication\ex_loadsave.exe

Load A from : C:\Users\mwuser\AppData\Local\Temp\mwuser\mcrCache9.13\ex_loa0\ex_loadsave\user_data.mat 
A=  
   21.4669   15.7255   15.6930   11.8122 
   19.6691   17.0570   17.4689   22.2803 
   20.3894   17.2548   17.3474   17.7316 
   19.3062   15.1321   16.0573   25.4584 
 
Load B from : C:\Users\mwuser\AppData\Local\Temp\mwuser\mcrCache9.13\ex_loa0\ex_loadsave\userdata\extra_data.mat 
B=  
   15.3970   20.5682   13.8388   26.5186 
   14.2255   24.6506   18.9545   24.8117 
   14.9904   22.8211   16.4942   25.3533 
   13.1022   26.0567   21.2197   24.8940 
 
Load extern data from : C:\Users\mwuser\AppData\Local\Temp\mwuser\mcrCache9.13\ex_loa0\Users\mwuser\Documents\Work\exfiles\externdata\extern_data.mat 
ext_data=  
   27.6923   69.4829   43.8744   18.6873 
    4.6171   31.7099   38.1558   48.9764 
    9.7132   95.0222   76.5517   44.5586 
   82.3458    3.4446   79.5200   64.6313 
 
A * B =  
   1.0e+03 * 
 
    0.9442    1.4951    1.1046    1.6514 
    1.0993    1.8042    1.3564    1.9424 
    1.0518    1.7026    1.2716    1.8500 
    1.0868    1.7999    1.3591    1.9283 
 
Save the A * B result to : C:\Users\mwuser\Documents\Work\exfiles\Data_Handling\output\saved_data.mat

Compare the results to the output of ex_loadsave.m.