Include Additional Files in Packaged Applications

R2026b

When you package a MATLAB® application for deployment, you may need to include additional files such as data files, configuration files, DLLs, or resources from other programming languages. These files are packaged into a deployable archive alongside your compiled MATLAB code. You can access included files in your MATLAB code using the which function or by referencing the file location relative to the deployable archive root ctfroot.

Include Files in Deployable Archive

MATLAB Compiler™ uses a dependency analysis function to automatically 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 using one of the following, depending on your packaging method.

  • The AdditionalFiles option with a compiler.build function, such as compiler.build.standaloneApplication

  • The Custom Requirements section in a compiler app

  • The -a flag with the mcc command

t or the

For information on selecting a packaging method, see Choose Deployment Option.

Include MEX Files, DLLs, or Shared Libraries

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

  • Since the dependency analysis function 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 a MATLAB function called by a MEX file, DLL, or shared library can be found during dependency analysis, 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.

Explicitly Include MATLAB Data Files Using %#function Pragma

The compiler excludes MATLAB data files (MAT files) during 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

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 are placed under a subdirectory named after the main application file (truncated to 12 characters), and the relative path from the working folder to the file is preserved beneath it.

    For example, if the working folder is D:\Documents\Work\MyProj, and the main file is example_mainfile, then the file D:\Documents\Work\MyProj\exfiles\data1.mat will be located at ctfroot\example_main\exfiles\data1.mat in the deployable archive.

  • 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
    mainName = "example_mainfile";
    mainName = mainName(1:min(end, 12));  % truncate to 12 characters
    locate_data1 = fullfile(ctfroot,mainName,"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.

  1. Copy the Data_Handling and externdata folders that ship with MATLAB to your working 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.

  2. 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

    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');

  3. Create a cell array that lists the data files.

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

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

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

  5. 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

  6. Compare the results to the output of ex_loadsave.m.

See Also

|

Topics