# Makesis example projects

## Contents

- Overview
- Installing a simple program
- Installing a multi-lingual program
- Running a file on EPOC machine during installation
- An installation incorporating other installation files

## Overview

The `makesis` example projects demonstrate how `.sis` installation files are built using the `makesis` tool. They are provided with all SDKs which supply the EPOC Tools and Utilities documentation, see directory `\epoc32ex\adk\`.

The examples are primarily concerned with the configuration of `.pkg` files, see Package file format, as they define the components which are bundled into the `.sis` file, and hence the files which are ultimately installed on the target EPOC system.

The example applications are trivial, and are included purely for the demonstration of `makesis`.

## Installing a simple program

The minimal application `ikhello` is used to demonstrate the most basic `makesis` functionality. The application prints `Hello World!` on the screen in English. It is comprised of two files `ikhello.app` and `ikhello.rsc`, located in the directory `\epoc32ex\adk\`, which must be installed into `\system\apps\ikhello\` on the target machine. Rather than manually creating this directory and copying the files into it, a `.sis` file may be produced to automate the installation procedure.

  makesis flowchart - installation of a simple program

The package file `ikhello.pkg` (see Package file format) defines the source files to be bundled in the `.sis` file, and the folder location to which the files are to be copied.

        #{"Minimal application"},(0x01000508),1,0,0
        ; Only two files to install for the minimal application
        "\epoc32ex\adk\ikhello.app"-"!:\system\apps\ikhello\ikhello.app"
        "\epoc32ex\adk\ikhello.rsc"-"!:\system\apps\ikhello\ikhello.rsc"

The first line is the installation header, which defines the application’s name, `Minimal application`, UID3 (0x01000508), major and minor build numbers (1 , 0) and the variant number (0). The second line is a comment. The final two lines specify the files which should be installed and their destination on the target machine.

##### Notes

- There is no initial language line because the application only supports UK English (the default language).
- The UID is a unique number, used by EPOC to specify the application. For more information on the UID, review the documentation for your SDK (C++, OPL, Java).
- The application's major and minor build numbers are required for version control (eg. `AppName 3.1` specifies a major build 3, and minor build 1.)
- The variant number is not currently used by `makesis`, and may be omitted. Eventually EPOC applications may require a variant number, to distinguish between application builds for different target platforms.
- Lines preceded by a semicolon are comments — not used by `makesis` as part of the build process.
- Since the target drive is (probably) not known by the developer, it must be selected by the user during installation. This is indicated in the `.pkg` file by specifying ! as the destination drive.
- If directories in the installation path do not exist, they are automatically created by EPOC Install.

To create the installation file `ikhello.sis`, invoke `makesis` on the package file:

        makesis ikhello.pkg

`ikhello.sis` can then be installed on the target machine using one of the methods described in the topic Installing EPOC applications. After installation the application may be run by selecting the `ikhello` icon on the extras bar.

## Installing a multi-lingual program

This example demonstrates how to configure a `.pkg` file for installing applications supporting more than one language. It uses the same application as in the previous example, but prints `Hello World` in English, French or Italian, depending on the language selected by the user during installation.

EPOC supports different languages through the use of resource files, see Resource compiler). Each resource file contains, in a different language, the text used by the application (e.g. in menu options). The `.sis` file bundles the resource files belonging to all languages, but EPOC Connect transfers only the file supporting the language selected.

The following diagrams show the process more clearly. The `ikhello` application file can link to one of three resource files produced by the resource compiler. When `makesis` is invoked with the appropriate package file, `ikhellom.pkg`, all four files are bundled into the `ikhellom.sis` file.

  Installation flowchart - packaging a multi-lingual program

During installation, EPOC Connect selects the resource file associated with the user’s preferred language. Since `ikhello.app` can only link to a file with an extension `.rsc`, the file’s extension is changed when it is installed. The installation process is shown in the diagram below.

  Installation flowchart - installing a localised version of a multi-lingual program

The package file `ikhellom.pkg` defines the source files to be bundled in the `ikhellom.sis` file, and the folder locations to which the files are to be (optionally) copied.

        &EN,FR,IT
        #{"Minimal application", "Application minimale", "Applicazione minima"},(0x01000508),1,0,0
        "\epoc32ex\adk\ikhello.app"-"!:\system\apps\ikhello\ikhello.app"
        {
        "\epoc32ex\adk\ikhello.ruk"
        "\epoc32ex\adk\ikhello.rfr"
        "\epoc32ex\adk\ikhello.rit"
        }-"!:\system\apps\ikhello\ikhello.rsc"

The package file is similar to that in the preceding example. The notes below cover only the additional features.

##### Notes

- The first line specifies the language variants which are supported (see Languages).
- The second line, the installation header, includes the component name, translated into the relevant languages. The order of the headings must be the same as the language declaration in the first line.
- The third line specifies the application file to install; unlike the resource files, this does not depend on the language chosen.
- The final component lists the resource files and their destination. Of the three files specified, only one will be installed (depending on the language chosen by the user during installation). Consequently there is only one destination file.

To create the installation file `ikhellom.sis`, invoke `makesis` on the package file:

        makesis ikhellom.pkg

## Running a file on EPOC machine during installation

This example demonstrates how to configure a `.pkg` file so that a text file is viewed on the PC, and a file is automatically run on the target platform, during installation. It uses the same application as in the first example, but additionally displays a license agreement during installation. Also, during installation of the application, an EPOC Word document is run on the target machine.

The following diagrams show the process more clearly. The `sis` file bundles the same `ikhello` application and resource files as in the first example. It also bundles a license agreement and de-installation notice.

  Installation flowchart - packaging the program and license agreement

As shown in the diagram below, the license agreement is displayed during installation, but is not copied to the target machine. The de-installation notice is transferred to the target machine, and is run when the application is installed/removed — see Installing applications.

  Installation flowchart - installing the program with license agreement

This package file used for this example, `ikhellol.pkg`, is shown below. The following notes cover only file features which are additional to the previous examples.

        #{"Application with licence"},(0x01000508),1,0,0
        "\epoc32ex\adk\ikhellol.txt"-"",FT,TA
        ; Files to be installed - only three, no language variants
        "\epoc32ex\adk\ikhello.app"-"!:\system\apps\ikhello\ikhello.app"
        "\epoc32ex\adk\ikhello.rsc"-"!:\system\apps\ikhello\ikhello.rsc"
        "\epoc32ex\adk\ikhellod"-"!:\system\apps\ikhello\ikhello-deinstall",FR,RI

##### Notes

- The second line specifies the file to be displayed during installation. The arguments specify that the file is text to be displayed during installation but not installed (`FT`), and that EPOC Connect should display a `Yes/No` dialog instead of the default Continue (`TA`). The dialog aborts if `No` is pressed. Since the file is not installed, the destination is represented by empty quotes.
- The final line specifies a file to be installed and run on the target EPOC machine using the argument FR. The argument `RI` indicates that the file is to be run only during installation.
- To run, the file specified in the final line must be in EPOC native format — e.g. an EPOC Word document.
- It is possible to specify that an installed file should run during removal. However, since the file is deleted in the process, this facility should only be used for small, fast executing, files: for example, a file to clean up the registry or other parts of the system.

To create the installation file `ikhellol.sis`, invoke `makesis` on the package file:

        makesis ikhellol.pkg

## An installation incorporating other installation files

This example demonstrates how to configure a `.pkg` file so that the new installation file bundles other `.sis` files. This feature might be used for packaging different parts of an application, e.g. user interface and engine, prior to generating a complete installation file for the whole application. It might also be used as a means of preventing components from being overwritten by earlier versions.

  makesis flowchart - bundled sis file

The diagram above illustrates the bundling process. The `ikhellos` package file specifies an installation file which includes the `BossPzzl.sis` file. During installation, shown below, `BossPzzl.sis` is extracted from the `ikhellos.sis` file and its contents, `BossPuzzle.hlp`, automatically installed.

  Installation flowchart - installation of bundled sis file

The package file used for this example, `ikhellos.pkg`, is shown below. The following notes cover only file features which are additional to the previous examples.

        #{"Minimal application"},(0x01000508),1,0,0
        ; Ikhello installation with an embedded .sis file
        "\epoc32ex\adk\ikhello.app"-"!:\system\apps\ikhello\ikhello.app"
        "\epoc32ex\adk\ikhello.rsc"-"!:\system\apps\ikhello\ikhello.rsc"
        ; Component .sis files
        @"\epoc32ex\adk\BossPzzl.sis",(0x01000508)

##### Notes

- The final line specifies the file to be installed, `BossPuzzle.sis`, and a UID. A help file has no UID. Since `makesis` requires a UID to build the installation file, a dummy UID has been used.
- This example is provided for illustration, and in no way demonstrates the recommended method for installing a help file.

To create the installation file `ikhellos.sis`, invoke `makesis` on the package file:

        makesis ikhellos.pkg