Faq obtain or use recompilation license for PLS Toolbox

From Eigenvector Research Documentation Wiki
Revision as of 10:01, 24 July 2019 by imported>Scott
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Issue:

How do I obtain or use a recompilation license for PLS_Toolbox?

Possible Solutions:

The standard PLS_Toolbox license does not permit recompilation of any part of the code without written permission from Eigenvector Research, Inc. This permission is usually in the form of a recompiliation license (for more information on recompilation licenses, see: our Blog post on Compiling PLS_Toolbox ).

If you have purchased a recompiliation license for PLS_Toolbox and/or other Matlab-based Eigenvector Research products, you can use the following instructions to compile your application including the licensed Eigenvector Research (EVRI) code.

  1. A zip file containing your compilation license file should be avaialable from the Other Files tab in your account on the Eigenvector website. Unzip the file to get your evrilicense.lic file. These files/codes are version dependent so be sure to use the correct license code for your version of PLS_Toolbox. For example, if you are using PLS_Toolbox version 8.7.1 then you should be using a license code meant for PLS_Toolbox 8.7.X rather than PLS_Toolbox 8.6.X. If you were not supplied an evrilicense.lic file by EVRI, create one by copying the license code supplied for your compilation license (found on the download tab of your EVRI account) into a plain-text file named: evrilicense.lic The file should consist of the license code on a single line of the file. For example:
    12345678-98765432-ab-1234-1234
  2. Copy the evrilicense.lic file into one of the folders on your Matlab path. This could be either one of the PLS_Toolbox folders, or your application's folder.
  3. Add the evrilicense.lic file to the "Shared Resources" list in the Matlab project builder. This will assure that the EVRI license gets included in the compiled application.
  4. Compile your application as usual using Mathworks' standard instructions. The Matlab dependency logic will automatically include the PLS_Toolbox functions in your compiled application. (See note below regarding "blocking" certain functions from being included.)

Blocking Unnecessary Functions

By default, Matlab's compiler automatically identifies all m-files which are necessary to run your application and includes all of these in the compiler output. Because of the integrated nature of many of the PLS_Toolbox functions, this can lead to "sprawl" - inclusion of many more functions than are actually needed. The follow steps can be taken to reduce the size of a compiled application:

  • Remove the PLS_Toolbox/dems, PLS_Tooblox/help and PLS_Toolbox/utilities/guis folders from your Matlab path prior to compiling. Files in these folders should be unnecessary for compilation.
NOTE: If you get an error mentioning "undefined function" try adding PLS_Toolbox/utilities/guis back to your path. I could be that a utility function in that folder is getting used by your code.
  • Add "dummy" functions to reduce dependencies:
One way to help reduce these unnecessary additions is to create empty "shell" functions to overload certain PLS_Toolbox functions. These functions, if placed in a folder above PLS_Toolbox when you are compiling, will shadow (hide) the actual function and help avoid sprawl. In particular the following functions are useful to shadow:
  • analysis.m
  • browse.m
  • plotgui.m
  • editd.m
  • evriinstall.m
  • evrireporterror.m
These functions will not be called in normal operation and, in most cases, our compilation licenses do not permit their inclusion in your application anyway.
Example of a "shell" function:
function analysis

Use the following function to create the files:


function make_pls_toolbox_overload
%MAKE_PLS_TOOLBOX_OVERLOAD - Create empty versions of PLS_Toolbox functions.
% This function will create "shell" functions of highly interconnected
% PLS_Toolbox functions to reduce the size of applications being compiled
% with PLS_Toolbox command line functions.

%Instructions:
% * Create a folder and add it to the top of your Matlab path.
%
% * Copy this function to the folder and run it to create shell functions.
%
% * Remove the PLS_Toolbox/dems, PLS_Tooblox/help and
%   PLS_Toolbox/utilities/guis folders from your Matlab path.
%
% * Compile your application and test.

flist = {'analysis.m' 'evrireporterror.m' 'plotgui.m' 'browse.m' ...
  'figbrowser.m' 'editds.m' 'evriinstall.m' 'trendtool.m' 'evrireporterror.m'};


for i = 1:length(flist);
  try
    fileID = fopen(flist{i},'w');
    fprintf(fileID,'function %s\n 1',flist{i}(1:end-2));
    fclose(fileID);
  catch
    try
      fclose(fileID)
    end
    disp(['Error trying to create: ' flist{i}])
    disp(lasterr)
    disp('Continuing to create files...')
  end
end


  • Find top level functions and see if you can "manually" determine dependencies. Look at the results of the top level dependency check and see what functions are called from the primary PLS_Toolbox function you're working with. If the dependencies are few, you may be able to iterate over the results (get 'toponly' dependencies from results) and get a smaller subset of dependencies. NOTE: This will require some experimentation and time to work through. The dataset object is extensively used by most function so this folder should almost always be included.
 [fList, pList] = matlab.codetools.requiredFilesAndProducts('peakfind','toponly') 
  • Use the Matlab profiler to analyze your code to determine what files are needed.

Uninstall the Stats Toolbox

Although moving the Stats Toolbox below PLS_Toolbox on your MATLAB path (or removing the Stats Toolbox folders altogether) will allow the PLS_Toolbox DataSet Object to function normally, you must uninstall the Stats Toolbox before compiling PLS_Toolbox function that require the DataSet Object.

The MathWorks states:

"When you compile [a program] into an application and run it, the MATLAB Compiler Run-time references its in-built Dataset function which is higher in its PATH and hence runs the data against this inbuilt Dataset function."

For more information on the DataSet Object history see here:

Troubleshooting

  • In some cases PLS_Toolbox may need to be moved out of the default installation folder into a folder with more permissions and/or no spaces in the path. For example, "C:\eigenvector\PLS_Toolbox".

Still having problems? Please contact our helpdesk at helpdesk@eigenvector.com