# Installing EPOC applications

## Contents

- Overview
- Installation and removal from the end user's perspective

- Installation
- Removal
- The Control Panel
- EPOC Connect
- Installation failure

- Installation from the developer's perspective

- EPOC Installation Files
- Compatibility issues
- Installation without EPOC Connect

## Overview

This section provides a comprehensive discussion of the EPOC installation process. Application installation and removal are described from both the end user and application developer’s perspective.

## Installation and removal from the end user's perspective

Section Contents

- Installation
- Removal
- The Control Panel
- EPOC Connect
- Installation failure

### Installation

Application installation consists of moving files from one place, e.g. on a PC or the Internet, to the correct folders on an EPOC machine. There are three ways for end users to install an application on an EPOC machine:

- install the EPOC installation `.sis` file directly from a PC, using EPOC Connect
- copy an EPOC installation file into the EPOC machine, from a PC or the Internet, then use the control panel’s `Add/remove` program to install components from the `.sis` file. Note: see The add/remove program for a discussion on compatibility issues related to the `Add/remove` program.
- copy files directly into the correct target folders. This option is not recommended for end-users.

The following diagram illustrates the two recommended methods for installing applications using the EPOC installation procedure:

EPOC installation files are generated by the `makesis` tool, and provide the most simple method for users to install applications on EPOC machines. For documentation of the `makesis` command line syntax, see Create software installation file — `makesis.exe`.

##### Notes

- Applications with high build numbers replace, without warning, applications with lower build numbers.
- The control panel’s `Add/remove` program does not allow low build number versions of a program to be installed over a higher build number version. In order to do so, the installed version must first be removed.
- Installation from a PC allows over-writing of high build number versions of an application by low build number versions, but only upon acknowledgement of a confirmation dialog.
- Application installation information is stored in residual `.sis` files, or stubs, which are created in the `\system\install\` folder of the EPOC machine’s destination drive during installation. These files should not be deleted by the user, as they provide the information needed by the control panel to display the list of installed programs, including program name, language, and build numbers. They also provide the dependency information required when removing programs, including information on the files which should be deleted and their location.

### Removal

Application removal consists of deleting files that are no longer needed from an EPOC machine. There are two ways to remove an application:

- if the application was installed from a `.sis` file using a recommended method, then it can be removed using the `Add/remove` icon on the control panel.
- if the application was installed by directly copying files, the files must be specifically located and deleted.

Copying and deleting files is recommended only during application development. Normally, applications should be installed or removed using EPOC’s installation facilities.

### The Control Panel

The `Add/remove` icon on the EPOC control panel invokes EPOC’s install/uninstall application. The application’s interface lists all installed programs, and provides options to remove installed programs, and to add new programs.

The end user may install a program by selecting the `Add new` button on the `Add/remove` dialog. This invokes a file browse dialog, which allows the user to select the EPOC installation file to install. Alternatively, users may directly install a selected installation file by opening its icon in the system screen. Both methods have the same effect.

Removing an application using the `Add/remove` dialog deletes all application components, excepting those required by other EPOC-installed applications. The uninstall process first ensures that a component is not used by another application. This includes applications installed on another disk. If any components are used by another application they are not deleted.

### EPOC Connect

EPOC Connect can be used to install application files from a `.sis` file on a PC, without transferring the `.sis` file itself to the target machine. This provides a convenient form of installation from a PC. It also avoids the need to use target machine disk space for the `.sis` file.

In order to install software from a PC, all the end user must do is double-click a `.sis` file from Windows Explorer. EPOC Connect recognises the file type, and launches the installation program. Alternatively, EPOC Connect may be used to install the `.sis` file from a command line.

### Installation failure

If an installation is aborted, the partially installed application will be marked as `Partial` in the control panel's list of installed applications. The end user can either re-install the application, or can remove it then start again. Note that when re-installing using the control panel’s `Add/remove` program, the user will be given the option of continuing with the installation rather than carrying out a complete re-installation.

## Installation from the developer's perspective

Section Contents

- EPOC Installation Files
- Compatibility issues

- epocinst
- The add/remove program

- Installation without EPOC Connect

### EPOC Installation Files

EPOC Installation (`.sis`) files are the starting point of installation for end users — whether they install from a PC using EPOC Connect, or whether they upload the `.sis` file to their EPOC machine and install using the control panel. A developer therefore must be able to make and deliver `.sis` files for installation.

`.sis` files are constructed by the `makesis` tool, as described in Create software installation file — `makesis.exe`. They contain:

- a compressed form of the files that are to be installed, assembled by `makesis` from various directories on the developer’s PC
- specifications for the directories on the target EPOC machine to which to install these files
- specifications about which common libraries are needed by the application: these specifications are used to ensure that, when the application is removed, common libraries are deleted only if they are not needed by the remaining applications
- specifications about language-specific files, so that a `.sis` file may contain the materials needed to install in several languages, but only one language variant is installed

All these specifications are passed to `makesis` by a control file with a `.pkg` extension.

### Compatibility issues

#### epocinst

`epocinst` is a component of EPOC Connect which allows the direct installation of `.sis` files from a PC connected to an EPOC machine. It was not available in the first release of EPOC Connect, also badged as PsiWin 2.0. To allow direct installation, users with this release of EPOC Connect must either upgrade to PsiWin version 2.1 or 2.2, or install `epocinst` separately. PsiWin upgrades can be download free from the Psion website.

In order to find out whether a copy of EPOC Connect needs to be upgraded, the end user should select the `My EPOC machine` icon in Windows Explorer. If the `Install New Program` option is not available under the EPOC menu, `epocinst` must be set up by running its installation program `setup`. Note that in some older versions of EPOC Connect the Windows Explorer icon is `My Psion`, and the menu to select is `Psion`.

It is recommended that `setup` be supplied by developers in a suitable form as part of their installation package, for example in `\epocinst\setup.exe` and that text be included in the installation instructions informing end users with PsiWin 2.0 who have not yet run `setup` that they should do so.

#### The add/remove program

The `Add/remove` program, in the EPOC machine's Control panel is supplied on the EPOC release 5 ROM. However, it is supplied for EPOC release 3 and 4 as part of the Message Suite, and it is not available on EPOC release 1 or 2.

### Installation without EPOC Connect

An issue for developers is how end users without access to a PC which is capable of running PsiWin 2.x can install software.

There are several possibilities:

- upload from Web using browser
- copy from another EPOC machine using Infrared or a Memory disk which contains the software
- dial-up to a BBS using the Comms application, and upload using XMODEM/YMODEM
- use another desktop connectivity package, e.g. EPOC MacConnect
- copy files using PsiWin 1.x

Using any of these methods, the easiest general solution to installing a complex application is for the user to:

- copy `setup`, supplied with the EPOC SDK in `\epoc32\release\marm\rel\`, and run it on the EPOC machine. This installs the `Add/remove` icon on the control panel. The user may run `setup` by opening its icon in the system screen. This will install all necessary files into the appropriate directories. `setup` will delete itself after it has executed.
- copy the software package's `.sis` file, and install by opening it on the EPOC machine.