If you've developed a new program or want to package an existing product for Athene, you can use our native installation program, QikInstall, to handle the entire installation process. All that is required is that you write an installation file describing the package and the instructions to install it to the user's PC. QikInstall works cross-platform and provides support for user friendly features, such as selecting optional components and defining the directories to which the software should be installed. Packages designed for QikInstall are stored in ZIP format to ease the compilation process and simplifies accessibility.
QikInstall is only available with Athene, so it may not be practical to use it if a program has been designed purely for the Pandora Engine. If you can't use QikInstall, 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 or bash script 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.
The most important and useful feature of QikInstall is that it provides an official 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.
Install packages are distributed as compressed files and use a '.install' extension to formally identify them. The compression format that is used can be any type of format, so long as it is supported by Athene. Currently ZIP compression is the only format that we recommend, as zip files are fast to access and it is easy to update and restore individual 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:
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 (make sure you give it a '.install' extension) and then load it into QikInstall. Once you are satisfied with the package configuration, 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. See rocklytefiles.com for making package submissions.
Note: In Linux, we recommend using Athene's native compressor if you need to store the permissions of each file (important for security measures and applying executable bit settings). You can use the compression object in DML scripts to create ZIP files, as in the following example:
The installation process starts from the first <install> tag (anything prior to that will be ignored) 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 standard. There is no predetermined order that you must follow in using these tags, but you must keep in mind that QikInstall will execute the script from top to bottom, following 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 (ENG) is assumed. Valid values for the language attribute are listed as three letter codes in system:config/languages.cfg.
Components Tag
If you need to split your installation into optional components, use the components tag. The components tag has no associated attributes. It contains option tags that define the available components and their dependency on each other. 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 same 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. It must contain a list of directory tags that will define the directory options. For example:
<directories>
<directory name="programdir" path="tools:keymaker/">
Destination for the Key Maker program:
</directory>
<component name="source">
<directory name="srcdir" path="user:source/keymaker/">
Destination for the Key Maker 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 directory tag has no dependencies, this ensures that it is a compulsory setting.
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.
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, "Usage Information"). The text needs to be written in plain UTF-8 characters embodied within the text tag. Word wrap is enabled by default, and it is recommended that each paragraph is formatted as a single long line to make full use of the word wrapping feature.
License Tag
The license tag is identical to the text tag in its functionality and format, but explicitly defines the text as a license agreement.
Break Tag
If the break tag is encountered at any stage of installation, the install process will stop. No errors or notifications will be printed, so this tag is typically used in conjunction with the text tag, for displaying a text message prior to the break.
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.
DML
Use the DML tag to execute DML statements during the installation process. There are no limits to what you can do with your DML script - running programs and other scripts is legitimate, as is the creation of standard DML objects. The DML statement must be embodied within the DML opening and closing tags.
Link
Use the link tag to create symbolic links from one file to another. This tag only works on file systems and operating systems that support symbolic links. Attributes used by the link tag include from, to and permanent. The to tag refers to the file or folder that you are linking to (i.e. the file should exist). The from tag refers to the location of the new symbolic link. The permanent tag may be specified if the link should remain after the package has been removed.
MakeDir
The makedir tag is used to create new directories on the user's file system. Attributes used by the makedir tag include dir, nofail and permanent. The dir tag specifies the location of the new directory. The nofail tag can be used to prevent failure in case the directory could not be created. The permanent tag may be specified if the directory should remain after the package has been removed.
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">bin:runscript</item>
<item name="Args">-script {programdir}/main.dml</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.
NoFail
The nofail tag can be used to prevent failures over a series of installation commands. To use, simply encapsulate the tags that you want to safeguard with the nofail tag.
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>
<command>bin:runscript</command>
<args>-script {programdir}main.dml</args>
<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.
Set
The set tag can be used at any time during installation to create a new variable, or change the value of an existing variable created during the installation process. To use, write a series of variable names and values as attributes within the set tag. For example:
<set desktop="no" sdk="1"/>
Please note that if any of the core tags fail in a way that is terminal, the installation process will be aborted at the point where the error occurred. Command tags processed during the installation process will also fail in the same way, but this can be prevented with the 'nofail' option.
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 same commands that are available for installation, i.e. copy, delete, run, rename, dml 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 removed by the user.
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:
