Whitepaper
Make Install Tool for Matlab®

By Norbert Marwan of the University of Potsdam, Germany, 2003

This whitepaper presents the Make Install Tool, which was developed to facilitate the distribution of Matlab toolboxes and programmes with a single installation script. It demonstrates the wide range capabilities of Matlab and the benefits, when Matlab standard parameters are used.

Related File Exchange File:

Overview

Introduction

During my work in nonlinear data analysis, a bunch of Matlab programmes and scriptes arised, which could be useful for other Matlab users. Programmes within a special topic can be summarized as a toolbox. Matlab provides some standard parameters and procedures, which allow the user to create own toolboxes and its embedding into the Matlab environment. Unfortunately, it seems that these features are not very well know. The most of the offered self written toolboxes do not use this great possibility. This can lead to a frustration for whose, who would like to use such a toolbox. However, a tool packing up the toolbox into one installation script, which can automatically install the toolbox on various platforms, should be very welcome. Since I needed such a tool for the distribution of my Matlab programmes, and I was not willing to pack them everytime by hand after each improvement, I have developed the technology and the Make Install Tool for such tasks. The Make Install Tool creates a single installation file, which contains the installation script and the archive with the toolbox files. In this article, an brief introduction about the Make Install Tool, the technology and some Matlab standards is given.

Basics behind the installation script

The installation script is that file, which will be created by the Make Install Tool. This file contains all files of the toolbox (ASCII as well as binary data) and an installation routine. Calling this file from the Matlab commandline extracts the toolbox and modifies the Matlab system in that way, that the toolbox is accessible by calling from the commandline and from the launch pad. In order to understand the mechanism behind this tool, some notes are given below.

Matlab standards used by the installation script

The first and maybe most important thing to be mentioned is the Matlab folder. On multi-user systems, every user can create its own Matlab folder in his home path, which can be automatically find by Matlab when it is simply called matlab. In this folder, a file startup.m can be filed which will be automatically executed when Matlab starts. By using this file, Matlab can be individually adjusted (e.g. for paper format, window colours). Moreover,  some system path variables exist, which contain the platform dependent filesystem structure. Matlab looks in all folders which are stored in the system variable path (or matlabpath). Since it is a system variable, it cannot be modified in the common way to change variable's contents in Matlab. Entries can be added or removed by the addpath and rmpath commands. The installation script applies these commands and adds a corresponding line to the startup.m file. Another usefule system variable is matlabroot.

The platform independence of file names can be kept by the application of the commands fullpath and fullfile as well as the Matlab variable filesep.

The next point is the structure of the Matlab M-files, which should contain the function definition line, the H1 line and the help text, finally in this order and not other. The H1 line supports, e.g., a search function for M-files (lookfor). References to other M-files should be in uppercase letters, because they will then be recognized by Matlab and, hence, work as a link in a helpbrowser.

Further, a file which is named Contents.m provides an easy access to all the functions in the toolbox folder. It is a basic component of the help system. The listed M-files should be written as they are named in the file system, because then they are working as links to these M-files. The first two lines of the Contents.m are parsed by the Matlab command ver. If the first line contains a string (the name of the toolbox) and the second line contains a string 'Version' followed by a version number and a date (dd-mmm-yyyy), these information will be shown by the command ver. The Make Installation Script can create such a standard Contents.m file by using the H1 lines of the programmes.

Since Release 12, Matlab provides a new working desktop with a command window, workspace manager, help dialog, launch pad etc. It supports an XML-based help system and new standards were grown up. E.g., the launch pad shows the self-written toolboxes if their folder contain a file named info.xml. However, it seems the development of the XML based help systems is not yet finished by Mathworks and, thus, should be carefully used (e.g. the content of the <area> field and the location of the icons have been changed from R12 to R13).

File storage

The main task of the Make Install Tool is to read all files in a folder and its subfolders and store it in a new file, from which they can be exactly extracted. In order to become more difficult, this new file should be executable within Matlab. However, the packed Matlab files have not to be executed by calling this install file, thus, an isolated container is needed. The trick is the following: first create an executable installation file, then add line-by-line the toolbox files, but each line begins with '%@'. The '%' guaranteed, that such lines can not be executed, the '@' was choosen arbitrarily. Each new stored file begins with a clear start line, which contains its name and ends with an end line:

%<-- ASCII begins here: __ace.m__ -->
%@function varargout=ace(x,y,w,ii,oi)
%@%ACE   Finds optimal transformation and maximal correlation.
%@%    MCOR=ACE(X,Y [,W,II,OI]) estimates the maximal correlation 
%@%    of the system theta(X)=phi(Y).
  .
  .
  .
%@end
%@x0=x3s; y0=y3s+ymean;
%<-- ASCII ends here -->

The next problem arises, when binary data should be involved too. The principle is similar to that of ASCII data. The binary data are stored byte-by-byte as a character, with a preceding comment sign '%'. The start line additionally contains the number of bytes of the stored binary data file:

%<-- Binary begins here: __crp_man.pdf__ __626194__ -->
%%%P%D%F%-%1%.%2%
%%%â%ã%Ï%Ó%
%
%2% %0% %o%b%j%
%<%<%
  .
  .
  .
%%%%%E%O%F%
%<-- Binary ends here -->

This allows to create an ASCII file, which can be executed from the Matlab commandline. The disadvantage is the uncompressed character of the file. Moreover, binary files become as double sized as original. A fast compression of the container data could be a future task.

Template for the installation file

The Make Install Tool has to create an apropriate installation script, which is able to extract the data container. This script is prepared and contained in the M-file of the Make Install Tool by the same principle as described above (a container at the end of the M-file).

How it works

Consider, we have a toolbox and need a single installation file, which contains all the files in the toolbox folder, can extract them automatically and modify the system variables. The easiest way to get such an installation file is the following:

  1. change into the toolbox folder
  2. call the Make Install Tool by 
    makeinstall

In the toolbox folder, an installation file will be created, which can be send by eMail or distributed by other ways, and those call will extract the toolbox on the destination system.

The exemplary output of the creation of the installation file for the MGUI toolbox:

>> makeinstall
   Reading the resource file
   Reading the install source code
   Source directory /usr/users4/marwan/matlab/MGUItool
   Create mguiclean.m
   Found version number 1.8.2
   Found release R3
   Time stamp 17-Mar-2003 12:33:38
   Modify Contents.m
   Reading Contents.m
   Reading gpl.m
   Reading info.xml
   Reading insight.txt
   Reading mgui.m
   Reading mgui.rc
   Reading mguiclean.m
   Reading private/inputdlg.m
   Reading private/logo.mat
   Reading private/waitbar.m
   Checksum is 7A914C0CF9
   Writing install.m

Possibilities

The easiest way to create the installation file is to call makeinstall in the toolbox path without any arguments. However, a finer attuned usage is possible.

The Make Install Tool needs some information about the toolbox, as its name and its folder. Simply, the current toolbox path will be taken for this information (e.g. a path like '/usr/home/marwan/matlab/CRPtool' will get the toolbox path 'CRPtool' and the toolbox name 'CRPtool'). However , sometimes the toolbox has a special name (e.g. 'Cross Recurrence Plot Toolbox'); this information can be provided as an argument in the makeinstall command.

makeinstall('Cross Recurrence Plot Toolbox')

It is possible to call makeinstall from outside the toolbox folder. Then the toolbox folder has to be given as an argument. Consider, we are in the folder '/usr/home/marwan/matlab'. The call

makeinstall CRPtool

or

makeinstall('Cross Recurrence Plot Toolbox','CRPtool')

will create the installation file of the toolbox in the path 'CRPtool'. However, the installation file will be filed in the current folder.

Since it should be convenient, when such information have not to be provided to the Make Install Tool each time, when it is called, these information are filed in a special properties file (makeinstall.rc) in the toolbox folder. This file will be automatically created, if it does not yet exist and can be modified with a simple text editor. It can contain further information about the toolbox, when a Web site is provided, a PDF manual is available etc. It will not read as a toolbox file and will not be deposited in the created installation file.

In order to embed the toolbox into the Matlab environment, the Contents.m and the info.xml file were created, if do not yet exist. For creation the Contents.m file, it is necessary that the M-files have the Matlab conform structure (function definition line, the H1 line and the help text).

In the following table, the available parameters used in the file makeinstall.rc are given.

Parameter
 Default
 Description
toolbox_name
 pwd Name of the toolbox.
install_file
 'install.m'
 Name of the installation script. This will be the name of the resulting file and the command for the installation.
deinstall_file
 'tbclean.m'
 Name of the deinstall script. Will be automatically created, if it does not exist. Removes all files, folders of the toolbox as the entries in the startup.m file.
old_dirs
Old toolbox folders. Sometimes toolboxes changes their names, but their old versions should be found and removed too.
install_path   The root folder where the toolbox folder will be created. The default is the location of the startup.m file ($USER$/matlab or $MATLABROOT$/toolbox).
install_dirUNIX toolbox_name The name of the folder in which the toolbox files will be extracted (Unix).
install_dirPC
 install_dirUNIX The name of the folder in which the toolbox files will be extracted (PC).
src_dir
 pwd
 Folder with the origin toolbox.
version_file
A file, in which a line with the version number of the toolbox is included. This line can be either
% Version: Number
or using the CVS keyword
% $Revision: Number$.
version_number
Alternatively, a version number can be given explicitely.
release
The release number of the toolbox.
infostring
Further information, which will be displayed as the last message after installation.

The next parameters effect the creation of the info.xml file. However, if this file already exist or is already created these parameters have no effect anymore until info.xml is deleted. Therefore, info.xml should be directly modified.

Parameter
 Default
 Description
xml_name
 toolbox_name
 Name of the toolbox in the launch pad.
xml_start
Start programme for the launch pad.
xml_demo
Demo programme for the launch pad .
xml_web
Link to the toolbox web site in the launch pad.


What happens during the installation?

Until now, it was presented, how the installation file will be created. However, what happens after calling this installation file on the destination system?

The installation file will firstly check the integrity of itself by using a checksum based method. After the test is passed, it looks for old installations of this toolbox by using the Matlab command which. For this purpose, the parameter old_dirs can be specified in makeinstall.rc. Found old toolboxes will be removed after question (startup entries will be removed too). Then a new entry ('addpath toolboxpath') in the startup.m file can be permanently added, in order to provide Matlab the access to the toolbox. The location of the entry in the startup.m (top or end, default is end) can be choosen. The platform independence of the used paths and filenames is kept by using the Matlab commands fullfile and filesep.

The container of the installation file will be read and each stored file will be extracted and saved into the destination toolbox folder. M-files will be p-coded, in order to accelerate the later execution of large Matlab programmes. On newer Matlab releases, the command rehash or rehash toolboxcache is called in order to force Matlab to find the new toolbox.

The exemplary output of the installation of the MGUI toolbox corresponding to the example above:

>> install
---------------------
  INSTALLATION MGUI
---------------------
  Reading the archiv 
  Checksum test passed (7A914C0CF9)
  MGUI2 version 1.8.2
  MGUI2 time stamp 17-Mar-2003 12:33:38
  Old MGUI toolbox found in /home/user_xyz/matlab/MGUItool
> Delete old toolbox? Y/N [Y]: n
  Importing the archiv 100% |******************************|
  Toolbox folder is /home/user_xyz/matlab/MGUItool
  Creating Contents.m
  Creating gpl.m
  Creating info.xml
  Creating insight.txt
  Creating mgui.m
  Creating mgui.rc
  Creating mguiclean.m
  Creating private/inputdlg.m
  Creating private/waitbar.m
  Pcode gpl.m
  Pcode mgui.m
  Pcode mguiclean.m
  Pcode private/inputdlg.m
  Pcode private/waitbar.m
  Creating private/logo.mat
> Delete installation file? Y/N [Y]: y
  Removing installation file
  Installation finished!
----------------------
For an overview type:
helpwin MGUItool

After the installation, the toolbox should appear by typing ver at the commandline. On some platforms with older Matlab releases, it seems to be necessary to restart Matlab in order to make the toolbox accessible.

To force another installation folder for the toolbox, the install file can be called with an argument:

>> install('/my/folder/')

Examples

An example of an installation file created with makeinstall can be found in the File Exchange area:
http://www.mathworks.com/matlabcentral/fileexchange/loadFile.do?objectId=2873

Another example with a more voluminous toolbox is the Cross Recurrence Plot toolbox, whose demo version is available at (the access to the full version is restricted yet):
http://www.agnld.uni-potsdam.de/~marwan/toolbox.html

Project web site

You can examine the project web site:
http://matlab.pucicu.de

MATLAB Central