%elements; %authors; ]> An introduction to creating ReST packages. &jefflarkin.author; &ericmeek.author; This document provides information for those interested in creating a ReST Installer package for a piece of software. It provides information detailing the process of package creation. It is assumed that the reader has at least a basic knowledge of the ReST project. 1.0 3/11/2005 Initial Public Release Although used primarily by the ReST Installer, ReST packages are the means by which the ReST Application Suite is customized for individual pieces of software. The ReST package contains the software and metadata needed by the Installer to install software on remote machines. The package metadata is used by the Installer and Explorer to maintain the state of installed software and in future versions of ReST it will contain information needed to customize the Monitor to work with the installed packages. In order to produce a well-written package it is important to understand what is contained in the package and what conventions are expected by the ReST Suite.

A ReST package is essentially a ZIP/JAR file containing two special files, a package XML file and a checksum file. The package XML file, name package.xml inside the package, contains both basic metadata about the package and instructions on how to install the package from source or pre-compiled binaries. The checksum file, at this time must be created by the ReSTPackager program contains checksums of each file within the package and is must pass before the Installer will run the package. Details about the package sources are not necessary, since they could be any file that is pertenant to the software being installed. Details about writing the package XML, including documentation of each XML tag, and creating the package file appear later in this document.

The package XML is what makes a ReST package special. It includes metadata pertaining to the software package, instructions on installing the contained software, and a list of actions that can be performed once the software has been installed. The XML file can be thought of as an enhanced shell script, since it contains a list of commands that are run sequentially to install the package. It is more than a simple shell script, however, in that packagers are able to define options that can be customized by the end user from the ReST Installer. Commands in the package XML are broken into six steps, which simply provide a logical grouping of the commands that are run. The six steps, in order, are Preparation, Configuration, Compilation, Installation, Complettion, and Uninstallation, with the last actually being optional. Commands that need to be run first, before anything else can happen, such as extracting archives or creating directories should be placed in the perparation step. Package sources will be sent to the remote machine and package directories will be created prior to this step. Anything pertaining to configuring the software, such as running a configure script should be placed in the configuration step. Configuration files included in the package will be sent to the remote machine between these first two steps. Commands related to compiling and installing the package should be placed in the next two steps respectively. During the completion step the packager should clean up the build area however possible, such as deleting unneeded sources that remain. Lastly, if a packager would like to provide a means for automatically uninstalling their software, commands pertaining to this should be placed in the uninstallation step. Each step is essentially equal, but provides a logical way of organizing the package. Packagers are encouraged to group their commands using these logical step. Every step except the uninstallation step must be in the package XML, but may be empty if not needed.

Future versions of the ReST suite may contain a graphical application for creating package XML files, but at the current time the file must be written by hand. For this reason it is crucial for the packager to gain an understanding of the package XML file to create a working package. Package XML files can be written in any text editor so long as they obey the rules defined for ReST XML. A definition of each XML tag is given in the reference sections at the end of this document.

The planning step is the most important part in successfully creating a working package. Before writing the XML create a step-by-step list of how the software is installed. If possible, walk through the installation in a clean /bin/bash environment, since this will more realistically reflect the environment in which ReST will install the software. Once this list has been written, place a mark next to each command that would not need to be run on every machine in an homogeneous environment with a shared filesystem. Now note command options that should be offered for each command, for example ./configure --with-foo. Try installing the software by walking through this list one command at a time; if it works without problem then fewer problems are likely to occur when the package is written.

The sections below will provide an overview of how to write a package XML file. For more detailed information about the XML tags, including advanced attributes, please see the reference section at the end of this document.

The package header contains metadata about the package that will be shared among all of the ReST applications. This metadata includes the name of the software, the author and version of the software, and information about the packager. Below is a basic package header. <header> <title>Example Package</title> <base>example</base> <version>1.0</version> <description>This package is an example ReST package.</description> <uri>http://icl.cs.utk.edu/rest/</uri> <licenseuri forceaccept="true">http://example.com/license.txt</licenseuri> <packager> <name>Joe Devloper</name> <uri>mailto:developer@example.com</uri> </packager> </header> There are several important tags in the above example. The title sets the package title that will appear in the Installer. If the title is longer than 25 characters, a second, shorter title may be set with the role attribute set to short. If no short title is provided and the title is longer than 25 characters, then in space-constrained parts of the application the long title will be truncated at 25 characters. The base element gives a way of grouping packages that should be installed in a similar area. For example, packages for the LAPACK and BLAS libraries have been written with a base of lib so that they, and other libraries, will be easy to find and use. The base should always be set to a value that will be valid for the filesystem on all target machines. The contents of the version tag should be the version on the software in the package and not the version of the package itself. The version of the package can be given as an attribute of the package root element if desired. Additional tags exist for the package header, including options for editing configuration files, added files to the package, and defining actions that can be performed once the package has been installed. All of these tags are defined with examples in a reference section at the end of this document.

As explained earlier, all commands for installing and uninstalling a package are organized into six logical steps: preparation, configuration, compilation, installation, completion, and uninstallation. The uninstallation step is optional, but recommended. These steps are essentially equal, except that configuration files are sent to the remote machine between the preparation and configuration steps. It is highly recommended that packagers take advantage of the six steps for logically grouping the package commands. Future version of the the ReST suite may contain optimizations or changes in the handeling of these steps and forward compatibility is best ensured by using these steps. Below is an example of the six steps appearing in a package. <preparation> <command value="tar -xf example.tar"> <command value="cd example/"> </preparation> <configuration> <command value="./configure --prefix=$PWD"> </configuration> <compilation> <command value="make all"> </compilation> <installation> <command value="make install"> </installation> <completion> <command value="make clean"> <command value="cd ..; /bin/rm -f example.tar"> </completion> <uninstallation> <command value="cd example"> <command value="make uninstall"> <command value="cd ..; /bin/rm -rf example/"> </uninstallation>

Some commands may need to be configured by the user before they are run on the remote machine. For that reason the ReST XML allows command tags to contain option tags. The option tags define command-line arguments for a given command and can be configured by end users. A good example of a command that will likely contain options is the ./configure script, which is included in many source distributions. It is common for this command to have many different command line options for properly configuring the build process. Below is an example of the ./configure command with options. <command value="./configure" grouped="true"> <option name="foo" type="text" default="/usr/local/lib/libfoo.a" truevalue="--with-libfoo="/> <option name="bar" type="boolean" default="false" truevalue="--with-libbar" falsevalue="--without-libbar"/> <option name="ouputlevel" type="choice" choices="debug,view,none" default="none" truevalue="--with-outputlevel "/> </command> The above example defines three possible options for the ./configure command. All of the options have four common attributes: name, type, default, and truevalue. The name attribute is exactly what would be expected, the name that the user will see when configuring this option. The type attribute may be either text, boolean, or choice. The default attribute defines what the value should be by default, which is required for installation in simple mode. Finally the truevalue attribute defines what is appended to the command if the option is enabled or if a option of type boolean is selected. For example, if option foo is enabled and the default value is left untouched the resulting string --with-libfoo=/usr/local/lib/libfoo.a will be appended to the command. Packagers are encouraged to expose all possible command-line options to the users through ReST as the packager is more knowledgeable about the software included than the user. Additional information about the option tag can be found in the reference section at the end of this document.

ReST actions are commands that exist on systems after a software package has been installed. For a piece of server software, for example, this could include starting, stopping, and restarting the server. An action is simply a wrapper around one or more command tags, much like each of the six steps described above, except that the action tag requires a name for the action. Actions can be run by the ReST Installer immediately after installation is complete or by the ReST Exploror at any time after package installation. Below is an example of package actions. <actions> <action name="Start Server" tooltip="Start a server."> <command value="/bin/bash ./start_server.sh" statusmsg="Starting Server" errormsg="Failed to start server."/> </action> <action name="Kill Server" tooltip="Kill a server."> <command value="/bin/bash ./kill_server.sh" statusmsg="Killing Server" errormsg="Failed to kill server."/> </action> <action name="Restart Server" tooltip="Restart a server."> <command value="/bin/bash ./kill_server.sh" statusmsg="Killing Server" errormsg="Failed to kill server."/> <command value="/bin/bash ./start_server.sh" statusmsg="Starting Server" errormsg="Failed to start server."/> </action> </actions>

Many software packages have configuration files that must be edited before the software can be used. To the developer of a software package writing the configuration files may be trivial, but this is often not the case for the end user. For this reason, the ReST Installer may be used to edit configuration files for the software package. The package must include a stub configuration file with a series of tokens to substitute. Each token appears with a % character on either side of the one-word token, such as %token%. With a stub file created the packager must define the substitutions for this file in the package XML. Below is an example stub file and matching package XML. FOO=%sub1% <configfile packagefile="example.cfg" remotefile="example/example.cfg" description="Example Configuration File"> <sub name="sub1" description="First Substitution" default="My First Substitution" type="string"/> </configfile> In the above example just one substitution is made, but ReST will handle as many substitutions as are needed. Three types of substitions exist, string (no more than one line of text), text (multiple lines of text), and choice (a defined set of choices, much like available for command options). The configfile tag has three attributes: packagefile (the location of the stub file in the package), remotefile (where the resulting configuration file should be placed on the remote machine), and description (a simple description for the user). Addtional information about the configfile and sub tags, including additional attributes to each, can be found in the reference section at the end of this document.

Once the package XML has been written, stub configuration files have been created and source files have been gathered, it is time to combine all of the files into a ReST package. Part of the ReST suite is the ReST Packager utility. This utility combines all of the necessary files into one package for easy distribution. Below is an example of how the ReST Packager is used. > java -jar ReSTPackager.jar -X examplepackage.xml -f example.rsp file1 file2 stub.cfg In the above example, the user has run the ReST Packager, which is included in the ReST suite to create a package named example.rsp. The -X argument tells the ReST Packager to use examplepackage.xml as the package XML file for this package. The -f argument tells the packager the name of the file to create. The remaining arguments tell the Packager which files to include. Every file that is declared in the package.xml must be included in the Packager arguments. The resulting file can be distributed by whatever means desired and used with the ReST Installer. Once the package file is created, it simply needs to be installed from the ReST Installer. To install the package, run the ReST Installer with the name of the package as an argument. The package can be local or placed on a web server, although larger packages will run more quickly if they are local. Here is an example of our package being used by the ReST Installer. > java -jar ReSTInstaller.jar example.rsp The ReST package specification was designed to give packagers a flexible system for creating an application installer for their software. This document should have given you the basic knowledge needed to build a package for your software. More detailed information about the ReST package XML, including a full example can be found in the reference pages of this document. For questions about ReST and to provide feedback or suggestions, please feel encouraged to e-mail the authors of this document. &elements.ref; Complete Package XML Example Show the complete XML of a package. &complete_package;