3-Lib banner

Using the Makesis installation tool

or:"Everything you wanted to know about Makesis but was afraid to ask"

Compiled for 3-Lib by John Forrest, treesoft@dial.pipex.com and Alan Richey www.rmrsoft.com

Contents:

    Sis File Purposes
    PKG Files
        Headers
        File Statements
        Sub-Components
    Producing International Versions
    Differences between Psion-based Install and PsiWin
    Comments
    Full Example
    Background
    Conclusion

The title says "Everything".  Well probably not everything, but you get the picture. Sis files are the way to distribute EPOC applications. Not only do they virtually automatically install the software, but they also allow the application to be easily removed from the machine - as well as showing version numbers etc. Sis files are generated on a PC using the makesis tool, available with both evaluation and full versions of the C++ and OPL SDKs. However, it is not always the most obvious tool to use. This page is intended to supply some does and don'ts, as well as a basic explanation. Hopefully you'll find it useful.

SIS FILE PURPOSES

The information in the .sis files is used for three related, but different activities:

After installation, or upgrade, of (say) sample.sis, a file "sample.sis" is created in \System\Install. It is important to realise that this is not the original file - it is information about the installed files only, and is used on upgrades and removal. During removal, all the files mentioned will be removed - Add/Remove does no analysis to see if other applications are still using certain files. This has important implications for the way you ship shared files - as we shall see.

A further point to realise is that upgrading is not exactly the same as removal followed by install - even though this impression is given by the install tool. In fact, certain files are left alone so that preferences etc are not lost - more on this below too.

You run the tool with the syntax:

> makesis sample.pkg

Which will generate "sample.sis". The real key to the tool, then, is the .pkg file format. We're going to illustrate this with an example taken from John's SoundTrans tool. The full example can be found at the end. This page contains most, if not all, of the things you need to know to get your own .sis files up and running.

PKG FILES

The pkg file is a standard text file, but it is not entirely free format - it consists of a number of lines which should not be split. The basic format of the file is as follows:

<header>
<file statements>
<sub-components>

We'll go through these items in turn, and then pick up some wider issues. Firstly some comments on the the role of the .sis files generated.

Headers

The header is two lines as follows:

&EN
#{"SoundTrans"},(0x10004247),1,03,0

The "&EN" says that the language in question is English - strictly speaking UK English. The second line contains further information. The string is the name of the app as it is used during installation. We suggest that this is exactly the same as the "caption" name - given in the .aif file for C++ and in the CAPTION statement in OPL. The hex number is a UID: it is actually the UID of the .sis file itself, and is used to tell if a package is already installed. It is normal practice to use the UID of the app itself.

The final three numbers are respectively the major and minor version numbers of your application and the variant number. The variant is supposed to equate with completely different versions of a module, but it is best ignored - the main install process uses the major and minor versions to work out which version is the most recent. It is good practice to give the minor version as a two figure number (as "03" here): a plain "3" would equate to "03" and not "30".

Be careful about the where you start numbering from; the first app John ever shipped using .sis files had the numbers "1,0" because he just copied the example from the manual. This was then v1.0 - even though it was just a beta. In the end, the first real version of the app was v1.10. "0,50" would have been more appropriate. However, you must increment the version numbers as you increment versions - a beta release following v1.10 (say) should have either a major or a minor number that is greater than 1 or 10 respectively, such as 1,11. That way the Install program will know it is a later version.

File Statements

The key to .pkg file are file statements, which typically say that a file is to be read from a place on your development PC and later installed somewhere on the target Psion. Here is a typical example:

"\epoc32\release\marm\rel\soundtrans.app"-"!:\System\Apps\SoundTrans\SoundTrans.app"

This says that soundtrans.app is to be copied from the Marm build area to a given folder on the target machine. It is very important that you give the full path name of the source file, except that you can omit the drive if it is your standard area. If you start using relative names like "..\buildarea", the EPOC version of the Install tool will not work. You can copy files to anywhere on the system - Install will create folders if required. We consider it good practice to use mixed case in the EPOC file names, so that for example folder "SoundTrans" and not "soundtrans" is created within system. However, this is up to you. The "!:" in the name indicates that the user can choose which drive to use - that is they can place it on drive D: if a compact flash card is installed. You should always use this feature, but it is essential that your program can be run from either drive. There is no good reason, these days, to issue a program that can only be run on drive C.  However, if it is REALLY essential, that some of the paths are hardwired, then explicitly use "C:" instead of "!:".

That covers the standard scenario, but there are several variations. The first variation is how to prompt users with dialogs such as "Do you agree with this licence file?" or "Do you want to continue with this install?". A typical example of this is:

"\SoundTrans\SoundTransapp\data\legal.txt"-"",FT,TA

Note the extra flags on the end of the command. FT says this is a text file to be used in a dialog, the particular behavior is then given by TA. With TA you get a Yes/No dialog such that if the user selects Yes installation continues and if No it is aborted. Alternatively with FT you can use TS where Yes means abort and No means continue, or TC where you instead get a plain Continue dialog. In neither variant is the text file installed on the Psion - it is just used for the dialog - so the destination path is given as "".

A further variation is when you want to run a program on install or remove. For example, with SoundTrans there is a program soundtranssetup.exe which is used to update the .ini file from one version to the next. This is achieved with the following:

"\epoc32\release\marm\rel\SoundTranssetup.exe"-"!:\System\Apps\SoundTrans\SoundTranssetup.exe",FR,RI

Here the FR flag says that the file is an executable program that might be run during installation or removal. The subflag RI says run during installation - it also runs during upgrading. Alternatives are RR for running during removal and RB for both installation and removal.

As a final section there is a way of telling the system about files that are not installed, but are created during use and should be deleted during a remove process. A typical example is the .ini preferences etc file. This is described as follows:

""-"C:\System\Apps\SoundTrans\SoundTrans.ini",FN

The key point here is the FN flag which states that a file is not to be installed but will be deleted during removal. Because there is no installation, the source path is blank. Notice that this file is explicitly denoted as "C:". This is because the standard Eikon practice is to use drive C to hold .ini files - even if the application is installed on drive D.  Also note that these files are not deleted during upgrades - just removal. (All other files are actually deleted during upgrading and then re-installed.)

Partly because of the last feature, we suspect, you will get no error messages if a file does not exist during removal or upgrade. If users remove any of your files, they can still upgrade or remove the application.

Sub-Components

The next section covers shared OPX's, library .dll files, etc. It is important that you do NOT include these as normal files, or when users remove your app they will delete the shared files even though other apps might be using them. We are going to assume that you have access to a .sis file containing the shared files you wish to install. If you don't, then you need to get one written - only create your own if you are the original author! Having multiple .sis files referring to the same shared files is just as confusing as including them directly.

SoundTrans depends on a shared module "TreesoftSupport". This is indicated with the following line:

@"G:\MiscSupport\TreesoftSupport\TreesoftSupport.sis",(0x0100017d6)

Note that the source pathname here is the .sis file you are depending on, and the hex number is its UID (from its header). What this does is to include TreesoftSupport.sis in with SoundTrans.sis. Although this makes the SoundTrans.sis larger, it avoids you having to tell users "also download and install XXX.sis". We recommend this method. Note that if you delete your app then the Operating System will check to see if other SIS-installed programs require the sub-component.  If no-one does then the sub-component is deleted.

There is an alternative way of indicating a dependence. You could write:

(0x0100017d6), 1, 12, 0, {"Treesoft Support"}

this says that this version of SoundTrans requires at least v1.12 of Treesoft Support, and you will get warning dialogs if it is not installed. Although this sounds attractive, in practice the only advantage is that the user will be told that a module is missing - he/she will still have to find and separately install it. The first method is more foolproof.

One related point. If you are creating a .sis file for a shared library, then it has essentially the same syntax as the example given below. Make sure it too has a unique UID - use the UID of the principle (or only) OPX/DLL. Use an appropriate caption name. It should be unique, so you may want to include the initials or name of your company or yourself. Whatever you do, DON'T use the same names and UIDs as your main applications.

Producing International Versions

The final aspect of the Makesis system is the ability to install different language versions of a program. Suppose, that in addition to the English 'soundtrans.hlp' file you also have a French 'soundtransFR.hlp' and German 'soundtransGE.hlp' file and you wish to give the user the option of which version to install. There are a few things you need to do to the PKG file described earlier :

Add French & German to the list of languages, so that instead of having the line

&EN
#{"SoundTrans"},(0x10004247),1,03,0

you have

&EN,FR,GE
#{"SoundTrans","SoundTrans","SoundTrans"},(0x10004247),1,03,0

(Note the three captions. These are the English, French and German captions respectively. Here they are the same, but could be translations of the program name if you wished. They should be the same as the CAPTIONS statement in an OPL program or the .aif file in C++. )

Put the 3 Help files in as options on the appropriate line. So, instead of

"Z:\System\Apps\SoundTrans\SoundTrans.hlp"-"!:\System\Apps\SoundTrans\SoundTrans.hlp"

you have

{
"Z:\System\Apps\SoundTrans\SoundTrans.hlp"
"Z:\System\Apps\SoundTrans\SoundTransFR.hlp"
"Z:\System\Apps\SoundTrans\SoundTransGE.hlp"
}
-"!:\System\Apps\SoundTrans\SoundTrans.hlp"

Note that the line is very similar, except you have surrounded the 3 files with curly brackets. Note they are given in the same order as the country definition. Now the program will install the appropriate file for the country selected.

Also note that the order of lines in the PKG file is crucial. You must put these language dependent lines in first, then followed by the language-independent lines (AIF, APP, MBM etc). When doing this with RMRBank, we get a residual installation SIS file of 1K. When we put them in the reverse order, the residual file size jumped to 120K !!

Differences between Psion-based Install and PsiWin

It is worth noting that there there are differences in behavior between the PsiWin install program and the EPOC equivalent, used when you open a .sis file on the Psion itself.

The first of these affects the original source, whereas the others may change the way you write your install instructions.

Comments

One point we didn't cover above is that of comments. As you can see, the syntax treats anything between ';' and the end of the line as a comment. Although it is not documented, you can use the '//' instead of ';' - giving C++ style comments. It is up to you.

Full Example

This is an example .pkg file belonging to an alpha version of John's SoundTrans program.

;PKG File
;
;  REM  First select countries to be supported
;
&EN,FR,GE
#{"SoundTrans","SoundTrans","SoundTrans"},(0x10004247),1,03,0
;
;  REM  Display some legal stuff
;
"\SoundTrans\SoundTransapp\data\legal.txt"-"",FT,TA
;
;  REM  Install the appropriate language resource file
;
{
"\epoc32\release\marm\rel\soundtrans.ruk"
"\epoc32\release\marm\rel\soundtrans.rfr"
"\epoc32\release\marm\rel\soundtrans.rge"
}-"!:\System\Apps\SoundTrans\SoundTrans.rsc"
;
;  REM  Install the appropriate help file
;
{
"\epoc32\release\marm\rel\soundtransUK.hlp"
"\epoc32\release\marm\rel\soundtransFR.hlp"
"\epoc32\release\marm\rel\soundtransGE.hlp"
}-"!:\System\Apps\SoundTrans\SoundTrans.hlp"
;
;  REM  Install the common program files
;
"\epoc32\release\marm\rel\soundtrans.app"-"!:\System\Apps\SoundTrans\SoundTrans.app"
"\soundtrans\soundtransapp\soundtrans.aif"-"!:\System\Apps\SoundTrans\SoundTrans.aif"
"\epoc32\release\marm\rel\soundtranseng.dll"-"!:\System\Apps\SoundTrans\SoundTransEng.dll"
"\epoc32\release\marm\rel\soundtransgsm.dll"-"!:\System\Apps\SoundTrans\SoundTransGsm.dll"
"\epoc32\release\marm\rel\sndtransrec.rdl"-"!:\System\Recogs\SndTransRec.rdl"
;
;  REM  Install the icon files 
;
"Z:\System\Apps\SoundTrans\slider.mbm"-"!:\System\Apps\SoundTrans\Slider.mbm"
"Z:\System\Apps\SoundTrans\SoundTrans.mbm"-"!:\System\Apps\SoundTrans\SoundTrans.mbm"
;
;  REM  Make sure the INI and REG files are removed on uninstallation
;
""-"C:\System\Apps\SoundTrans\SoundTrans.ini",FN
""-"C:\System\Apps\SoundTrans\SoundTrans.reg",FN
;
;  REM  Install the manuals
;
"\SoundTrans\SoundTransapp\data\SoundTransManual"-"!:\Documents\SoundTrans Doc\SoundTransManual"
"\SoundTrans\SoundTransapp\data\SoundTransReadme"-"!:\Documents\SoundTrans Doc\SoundTransReadme"
;
;  REM  Install the 'shared' files
;
@"G:\MiscSupport\TreesoftSupport\TreesoftSupport.sis",(0x0100017d6)

Background

Steve Litchfield asked us to write this page when John suggested his previous data on the subject could be updated in a number of ways.

Comments and corrections to direct to treesoft@dial.pipex.com, alan@rmrsoft.com or Steve himself.

Conclusion

If you came to this page wondering how to generate .sis files, we hope you've found it useful. All we can say is that even during development we habitually use these files to install apps onto Psions - it is so much easier and more predictable than hand copying. For end users, don't do anything else!