Distribution and Installation

Whether you've been developing a class, program or script, once you have reached a point where you wish to release your work, the immediate question is how you are going to do it. There are two possible methods that you can use, both of which are dependent on your situation. If you've developed a program which is based on the Pandora Engine only, your best (perhaps only) choice may be to use the native installation methods that are available on the target platform. On the other hand if your work is Athene or DML based, you can use the preferred option and write a installation script for the cross-platform compatible QikInstall program. In this document we will look at both methods of installation and provide a complete insight on writing installation scripts.

Native Platform Deployment

Native deployment is necessary in cases where you have developed a program specifically for the Pandora Engine and do not want to rely on users having Athene or DML installed on their system. This means that you will have to choose an installation method that is specific to the platform that you are targetting. For instance, if you are targetting Windows you will likely need to use a commercial installation package, while on Linux you might create a makefile for installation purposes.

You will also need to consider how you want the user to install the Pandora Engine binaries if they do not have it on their system already. There are two ways that you can do this: Either refer them to an Internet address where they can download the latest binaries (such as the Rocklyte downloads page) or you can install the binaries with your program. We have taken the liberty of waiving distribution rights on the Pandora Engine binaries so that you can include them with your program without prior licensing permission. The easiest way to install the binaries with your program is to simply provide the appropriate install package on your distribution media and tell the user to install it with your program. An alternative method is to take our installation apart and merge it into your program's installation. On Microsoft Windows this means going to the added effort of generating registry keys for the Pandora Engine (which you can find under HKEY_LOCAL_MACHINE\Software\Rocklyte\Pandora). On Linux you simply need to duplicate the procedure found in the Pandora Engine's installation makefile.

QikInstall Deployment

QikInstall is a program distributed with Athene and DML that is capable of installing any type of software or data on a system (programs, scripts, classes, documentation etc). The most important feature of QikInstall is that it provides a standard for the installation of Athene and DML based software. This standard, which is based on XML, ensures that there is consistency in the deployment and removal of software on a user's system. In this section we will discuss the XML-Install standard so that you can create your own installation packages. Before continuing, make sure that you try out the QikInstall software if you have not already. It is important to familiarise yourself with the way that the installation process works before diving in to create your own packages.

Background

Install packages are distributed as compressed files that have a '.install' extension. The compression format that is used can be any type of format so long as it is supported by Athene. Currently pkzip compression is supported and rar compression may be supported in future for the purposes of breaking large installation files into smaller data files. If you want to see the contents of any install package, try decompressing it using a pkzip decompressor so that you can examine the content. You will find that it will contain the software's data files as well as a special 'install.xml' file. This file contains the XML-Install code with commands that will tell QikInstall how to install the package. Here is an example install.xml file taken from Key Maker, a keymap customisation program for Athene:


<?xml version="1.0"?>
<!DOCTYPE install PUBLIC "-//ROCKLYTE//DTD INSTALL 1.0//EN" "http://www.rocklyte.com/dtd/install.xml">

<install language="english">
  <info>
    <name>Key Maker</name>
    <version>1.0</version>
    <author>Rocklyte Systems</author>
    <date>February 2002</date>
    <license>ODL</license>
    <description>
Key Maker is a program that allows you to create customised keymaps for
Athene.  It is particularly useful for international users that need
to create keymaps for their native keyboards, as well as people that
wish to assign special unicode symbols to specific key combinations.

The Key Maker source code is included in this archive under the Open
Development License.  This install package is freely distributable.
    </description>
  </info>

  <components>
    <option name="icon" value="on" text="Desktop Icon"/>
    <option name="source" value="off" text="Key Maker Source Code"/>
  </components>

  <directories>
    <directory name="programdir" path="scripts:tools/system/keymaker/">
      Destination for the Key Maker program:
    </directory>

    <component name="source">
      <directory name="srcdir" path="user:source/classes/tools/keymaker/">
        Destination for the Key Maker source code:
      </directory>
    </component>
  </directories>

  <installation>
    <!-- Register the keymaker class -->

    <component name="platform_windows">
      <register class="KeyMaker" id="8400" category="Tool" src="keymaker.dll" dest="classes:tools/keymaker.dll"/>
    </component>

    <component name="platform_linux">
      <register class="KeyMaker" id="8400" category="Tool" src="keymaker.so" dest="classes:tools/keymaker.so"/>
    </component>

    <!-- Register the program -->

    <register program="Key Maker">
      <desktop>{icon}</desktop>
      <text>Key Maker</text>
      <description>Generates keymap files for international keyboards.</description>
      <icon>icons:programs/tool</icon>
      <smallicon>icons:tiny/font</smallicon>
      <command>run src="programs:bin/runscript" args="-script {programdir}main.dml -target desktop"</command>
      <category>Development</category>
    </register>

    <!-- Install the program -->

    <copy src="script/*" dest="{programdir}"/>

    <!-- Source code -->

    <component name="source">
      <copy src="*" dest="{srcdir}"/>
    </component>
  </installation>
</install>

<!-- This tag enables the default uninstall method -->

<uninstall/>

At 78 lines, this install file is reasonably small. Even so, it provides the user with full information on what the software is and options as to how much of it should be installed and under what directories. It registers itself in the system's program configuration file and even detects what platform is being used and copies the appropriate binaries across. In other words, it won't take much of your time to write an installation script that contains all the necessary bells and whistles.

Creating an Install Package

There are two parts to building an installation package. The first is to determine what files you'll be including in the installation. We recommend that you create a special directory to hold the install files. If you have a lot of files to install, think about grouping them under sub-directories so that you can manage them easily. The second part is to write the install.xml file, which you can create by copying the following excerpt and saving it as 'install.xml' in the directory that you have created for file containment.


<?xml version="1.0"?>
<!DOCTYPE install PUBLIC "-//ROCKLYTE//DTD INSTALL 1.0//EN" "http://www.rocklyte.com/dtd/install.xml">

<install language="english">
  <info>
    <name>Name of your program</name>
    <version>1.0</version>
    <author>Your name goes here</author>
    <date>February 2002</date>
    <license>Freeware</license>
    <description>
      Describe the software in this section.
    </description>
  </info>

  <components>
    <!-- Optional components are listed here -->
  </components>

  <directories>
    <-- Customisable directory locations are specified here -->
  </directories>

  <installation>
    <!-- The installation process is defined here -->
  </installation>
</install>

<!-- This tag enables the default uninstall method -->

<uninstall/>

Please note that it is vital that the install.xml file lies at the root directory of the compressed package - don't place it in a sub-directory or the QikInstall program won't be able to find it. After developing your install file, you can test it by compressing the package into a zip file (give it a '.install' extension) and then load it into QikInstall. Once you have developed the package to a point of satisfaction you can distribute it through whatever channels are appropriate. We may also be able to help in distributing the package if you want to make it freely available to the public. Simply upload it to our FTP site's incoming directory (ftp.rocklyte.com) and if it interests us we may contact you to confirm distribution details.

Developing the install.xml File

The installation process starts from the point of the <install> tag and ends when the tag is closed. Within the install area you can specify any number of a series of special installation commands and data structures. In this section we will discuss these tags in detail so that you can get a complete insight on the extent of support provided by the XML-Install definition. There is no preset order that you must follow in using these tags, but QikInstall will execute the script in the order that you have specified. If you are unsure as to what order you should use in placing these tags, we recommend the following: info, components, directories then installation.

Install Tag

The install tag marks the start of the installation process. You must have at least one install tag in the XML file or no installation can be performed. Under normal circumstances you will define one install tag for the file, but if you want to support multiple languages then you will need to write an install section for each language that you want to support. You can specify the language used in an install section by setting the language attribute. If no language is defined then English is assumed. Valid values for the language attribute are as follows:

Afrikaans, Albanian, Arabic, Basque, Belarusian, Bulgarian, Catalan, Chinese, Croatian, Czech, Danish, Dutch, English, Estonian, Faeroese, Farsi, Finnish, French, German, Greek, Hebrew, Hungarian, Icelandic, Indonesian, Italian, Japanese, Korean, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovenian, Spanish, Swedish, Thai, Turkish, Ukrainian, Vietnamese

Components Tag

If you need to split your installation into optional components, use the components tag. The components tag has no associated attributes, but is used to contain a set of options. For example:

  <components>
    <option name="program" value="on" text="ZTerm Program"/>
      <option name="icon" value="on" text="Desktop Icon"/>
    </option>

    <option name="source" value="off" text="ZTerm Source Code"/>
  </components>

In this example we have created three options, the second of which has a dependency on the first. Dependencies tell the user that if the parent option is turned off, then the dependent options will also be unavailable. The attributes available for the option tag are name, value and text. The name that you choose for an option must be unique or it will override any tags that have used the set name. Keep the name of each option in mind as you will need to refer to them during the installation process. The value attribute indicates the default setting that you want to use for the option (valid settings are 'on' and 'off'). The text attribute is a short description of what the component is (limit your string to 40 characters).

For large installations it is recommended that you try to consolidate the available options so that the user is not overwhelmed. If you have more than 40 options, then you have too many. You should also limit the extent of nested options to no more than 4 levels of detail.

Directories Tag

The directories tag is used to give the user the option of selecting installation directories just before the install process takes place. The directories tag has no associated attributes, but is used to contain a set of directory options. For example:

  <directories>
    <directory name="programdir" path="programs:system/terminals/">
      Destination for the ZTerm program:
    </directory>

    <component name="source">
      <directory name="srcdir" path="user:source/programs/zterm/">
        Destination for the ZTerm source code:
      </directory>
    </component>
  </directories>

In this example two directory options are created, but the second is dependent on the 'source' component. If the user has not selected that option then the second directory will not be displayed to the user when directory selection occurs. The first option has no dependencies, which makes it a compulsory option.

The directory tag accepts name and path attributes. The name that you choose for a directory must be unique or it will override any tags that have used the set name. Keep the name of each directory in mind as you will need to refer to them during the installation process. The path attribute is the default setting for the directory option. You should decide on a sensible directory location here as it is likely that most users would accept the default. You will also notice that each directory tag contains text describing what the directory option is for (e.g. "Destination for the ZTerm program."). This is essential for letting the user know what each directory option is for.

Info Tag

The info tag is used to provide information on what an installation package contains. The info tag has no attributes but is associated with a variety of child tags. Each child tag contains content that is relative to the tag's name and you may specify as few or as many tags as you like. When the user tries to install your package, all the settings that you have provided will be read and displayed to the user so that he or she can make an informed decision as to whether or not to install your package. The info tags are as follows:

NAME: The name of the package (program or document name etc).

VERSION: The version number of the package, for example 1.0.

AUTHOR: Your name is entered here.

EMAIL: Your contact email address is entered here.

COPYRIGHT: A copyright string can be entered under this tag.

DATE: The date that you want to associate with the package. We recommend that you specify the date as the name of the month followed by the year, for example 'February 2002'.

LICENSE: The license that the package is distributed under can be entered here. Common licenses are 'freeware', 'GPL', 'PCL', 'shareware' and 'commercial'.

REQUIREMENTS: If your package has special requirements or only works on a specific platform, you need to list the requirements here. We recommend that you list each requirement using commas as separation marks.

PLATFORM: Similar to the requirements tag, the platform tag allows you to specify exactly what platforms are supported by your installation package. Allowable values for the platform tag are currently limited to 'Windows' and 'Linux'. If your package supports multiple platforms then you should list the name of each supported platform, separated by commas.

DESCRIPTON: A complete description of what the package is for should be entered here. You can enter as much information as is necessary to describe the package's content. We recommend that you write two to five paragraphs of text here.

Installation Tag

The installation tag is used near the end of the install process to do the actual installation of your package's files. The installation tag has no attributes but supports a series of commands that are used to copy, rename, delete, move files and more. During this process you may need to make references to some of your variables (such as those generated from component and directory options). You can declare a variable reference by enclosing its name in curly brackets. For instance, to refer to a directory option that was given a name of 'srcdir' you would refer to it as '{srcdir}' in your XML code. Please refer to the example provided earlier in this document to see how variables are used during the install process.

Currently the following command tags are supported:

Component / Test

Use the component and test tags for areas of your installation that are dependent on user selected options. When the install procedure encounters one of these tags, it will check to see whether or not that option is active. If it is, the install procedure will execute all of the commands within the tag. If the condition is not met, then everything inside the tag will be avoided. Here is an example:

  <component name="icon">
    <item name="Desktop">Yes</item>
  </component>

In the above case, the item tag will only be executed if the user chose to install the desktop icon component of the software. This raises another issue - sometimes you may need to execute a set of instructions only if the user has chosen not to select an option. To do this, just put an exclamation mark prior to the name attribute, as illustrated in this example:

  <component !name="icon">
    <item name="Desktop">No</item>
  </component>

Note that the test tag is a synonym for the component tag, so you can use either according to personal preference.

Copy

Use the copy tag to copy files from your package to the user's system. Attributes used by the copy tag include src, dest and nofail. The src tag indicates the source location and you may use wildcards if you need to copy multiple files. To copy directories, make sure that you place a trailing slash at the end of the string or the installer will assume that you are trying to copy a file. The dest argument must refer to the destination directory. If you have allowed the user to select directory locations, you may need to make a reference to one of your variables here. The nofail attribute can be used if you want to avoid failures during the copy operation.

Delete

Use the delete tag to delete files from the user's system. Use this command sparingly! The only attribute supported by the delete tag is src, which refers to the location that you want to delete. You may use wildcards if you wish to delete multiple files.

As you might imagine, the delete tag is more commonly used in the uninstall tag rather than during the installation process.

Merge

The merge tag is used to merge information into configuration files, which are usually identifiable by a '.cfg' file extension. Merging is a common requirement for registering classes in the system:config/classes.cfg file and programs in the user:config/programs.cfg file. If you haven't viewed these files in a text viewer before, we recommend that you do so before attempting to use this tag.

The merge tag accepts file, section and nofail attributes. The file attribute refers to the file that you want to merge with. The section must refer to the section of information that you want to add your data to (sections are identifiable in configuration files by their square brackets). The nofail attribute can be used to avoid failure if a merge is not possible.

To declare the information that is to be merged into the configuration file, you need to use item tags in the merge section. Each item tag requires that you specify a name and you must also include content that will be added to the data associated with that item. To illustrate, here is a complete example of a merge tag and its items:

  <merge file="user:config/programs.cfg" section="Key Maker">
    <item name="Desktop">No</item>
    <item name="Text">Key Maker</item>
    <item name="Description">Generates keymap files for international keyboards.</item>
    <item name="Icon">icons:programs/tool</item>
    <item name="SmallIcon">icons:tiny/font</item>
    <item name="Command">
      run src="programs:bin/runscript" args="-script {programdir}/main.dml -target desktop"
    </item>
    <item name="Category">Development</item>
  </merge>

If you want to merge with more than one section, you have the option of using the section tag to switch over to a new section area midway through the merge. If you use this tag, then all the following items that you use will be merged under the new section. Using the section tag means that you only need to specify one attribute, the name to indicate the name of the section that you want to switch to.

Finally, some important technical notes. If the file that you are merging with does not exist, the installer will automatically create a new configuration file at that location. If the file is loaded and it is found that the selected section exists in the file, your specifications will automatically overwrite any matching items in the file.

Move

Use the move tag to move files and directories to different locations on the user's system. The move tag supports src and dest attributes which indicate the source and destination locations respectively. You may use wildcards in the src tag if you have multiple files to copy. Do not attempt to use the move command to move files in your install package - use the copy command for this purpose.

Register

The register tag is used to register programs and classes in the system. The following example illustrates how to register a class:

  <register class="KeyMaker" id="8400" category="Tool"
    src="keymaker.dll" dest="classes:tools/keymaker.dll"/>

Registering a class requires that you specify the class, id, category, src and dest attributes of the tag. Each attribute reflects the values found in the sytem:config/classes.cfg file, except for the src and dest tags, which are used to copy the class binary from the package to the destination location.

This next example shows how to register a new program in the system:

  <register program="Key Maker">
    <desktop>{icon}</desktop>
    <text>Key Maker</text>
    <description>Generates keymap files for international keyboards.</description>
    <icon>icons:programs/tool</icon>
    <smallicon>icons:tiny/font</smallicon>
    <command>run src="programs:bin/runscript"
      args="-script {programdir}main.dml -target desktop"</command>
    <category>Development</category>
  </register>

The only attribute that you need to specify is the program tag, which reflects the name of the program. Try to keep the name unique so that it does not overwrite any existing program registrations. Within the register tag you need to list the attributes of the program by using child tags. Currently supported child tags are desktop, text, description, icon, smallicon, command and category. To further your understanding of program registration settings, try viewing the system:user/config/programs.cfg file for examples.

Rename

The rename tag can be used to rename files in the user's system. Simply provide the source location in the src attribute and declare the new name of the file or directory with the newname attribute.

Run

Use the run tag whenever you need to run an executable program, data file or script. You can even use it to run files that you have included in your installation package. The run tag accepts the attributes src, args, mode and nofail. The src is a compulsory setting that refers to the location of the file that you wish to run. The args attribute can be used if you need to send command line arguments to a program. The mode attribute defines what mode should be used in running the file - available modes include open, edit, view and print. The nofail attribute tells the intsaller not to fail if the program cannot be found or some other error occurs.

Text Tag

Use the text tag if you would like to print a message to the user during the installation process. The text tag is commonly used for printing license agreements, installation notes and readme information at the beginning or end of the install. Currently the text tag accepts one attribute, the title tag, which should summarise the body of text in about two to five words (for example, "License Agreement"). The body of text itself needs to be written in XML within the text tag. The format of the XML comes from the Text class, which is used to print the text information that you provide. Each paragraph needs to be enclosed in an item tag and if necessary you can enable font colours, bold and italic text using XML as described in the Text manual.

Please note that if any command tags fail in a way that is terminal, the installation process will be aborted at the point where the error occurred.

Providing Support for Software Removal

By default the installation process will not provide support for the removal of your software for the user. To add support for its removal you need to use the <uninstall> tag in your XML-Install file. When you use this tag the QikInstall program will make a note of what it has done during the installation process and will create a file which can reverse the process. This file is stored in the system at a user accessible location so that your software can be uninstalled at any time.

In some cases you may need to customise the uninstallation of the software if certain files need to be altered that were not originally covered in the installation process. You can do this by using the commands that are described under the <installation> tag, such as copy, delete, run, rename and move. Simply add the commands to the <uninstall> section of your XML-Install file and they will be processed at priority when the software is uninstalled.

Preset Variables

Earlier in this document we mentioned the use of variables, which are automatically created based on the names that you have given for user selectable options and directories. The installer also contains preset variables that can be important if you need to know what the status of the user's environment is. Currently the following preset variables are supported:

PLATFORM_LINUX: Set if the platform accepts Linux (ELF formatted) binaries. No distinction is made as to the CPU that is being used.

PLATFORM_WINDOWS: Set if the platform accepts Windows formatted binaries.

PLATFORM_MACX: Set if the platform accepts Mac OS X formatted binaries.

CPU_INTEL: Set if the platform is running on an Intel CPU or a CPU with a compatible instruction set (I386 or better).

CPU_PPC: Set if the platform is running on a Power PC RISC CPU.

CPU_MOTOROLA: Set if the platform is running on a Motorola CPU (68000 or better).


Copyright (c) 2002 Rocklyte Systems. All rights reserved. Contact us at feedback@rocklyte.com