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.