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:
- change into the toolbox folder
- 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
|