| Revision History | |
|---|---|
| Revision 1.0 | 3/11/2005 |
| Initial Public Release | |
Abstract
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.
Table of Contents
action
- Commands that can be run
after a package has been installed.actions
- Wrapper element for multiple
action elements.backgroundcolor
- Declare the background color
that should be used in the ReST applications when
referencing this package.backgroundimage
- Declare the background image
that should be used in the ReST applications when
referencing this package.base - Gives the base directory for this
package.checksumuri
- Give the uri to a file that
contains the checksum for this package.command
- Run a command on the remote
system.compilation
- The 3rd of the 5 steps to
installing a package.completion
- The 5th of the 5 steps to
installing a package.configfile
- Declare a file that must be
configured by the user.configuration
- The 2nd of the 5 steps to
installing a package.def - Defines a substitution or command option
in a pre set.description
- Provide a description of the
package.explorerattributes
- Contains attributes to
customize the look and feel of the ReST Explorer for a
specific package.header
- Provide basic metadata about
the package.icon - Defines the icon to appear in the
titlebar of a ReST application when referencing this
ReST package.info - Give additional information about the
software contained in this package.infouri
- Give a link to a text file
containing additional information about the software
contained in this package.installation
- The 4th of the 5 steps to
installing a package.installerattributes
- Contains attributes to
customize the look and feel of the ReST Installer for a
specific package.license
- Define the licensing terms
of the included software.licenseuri
- Define the licensing terms
of the included software.monitorattributes
- Contains attributes to
customize the look and feel of the ReST Monitor for a
specific package.name - Gives the name of the
packager.option
- Declares configurable
options for a command.package
- The ReST Package root
element.packagedir
- Declare a directory within
the structure of the package file.packager
- Information about the person
who created this ReST Package.packagesrc
- Declares a file that appears
in the ReST package.patch
- Declares a patch file to be
applied to the sources contained in this file. (NOT
CURRENTLY SUPPORTED)pre - A set of predefined options and
substitutions.predefs
- Provide groups of
pre-defined command options and configuration
substitutions.preparation
- The 1st of the 5 steps to
installing a package.sub - Defines a substitution that will be made
in a configuration file.title
- The title the will appear in
the ReST applications for this package.uninstallation
- An option additional step to
define how to uninstall a package.uri - A standard URI that may be used to
provide more information about a package or package
author.version
- Give the version of packaged
software.List of Examples
Table of Contents
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.
Table of Contents
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.
Example 2.1. 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.
Example 2.2. The 6 Steps
<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.
Example 2.3. Command 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.
Example 2.4. 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.
Example 2.6. Configuration File XML
<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.
Example 3.1. Running the ReST Packager.
> 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.
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.
Table of Contents
action
- Commands that can be run after
a package has been installed.actions
- Wrapper element for multiple
action elements.backgroundcolor
- Declare the background color
that should be used in the ReST applications when
referencing this package.backgroundimage
- Declare the background image
that should be used in the ReST applications when
referencing this package.base - Gives the base directory for this
package.checksumuri
- Give the uri to a file that
contains the checksum for this package.command
- Run a command on the remote
system.compilation
- The 3rd of the 5 steps to
installing a package.completion
- The 5th of the 5 steps to
installing a package.configfile
- Declare a file that must be
configured by the user.configuration
- The 2nd of the 5 steps to
installing a package.def - Defines a substitution or command option
in a pre set.description
- Provide a description of the
package.explorerattributes
- Contains attributes to
customize the look and feel of the ReST Explorer for a
specific package.header
- Provide basic metadata about
the package.icon - Defines the icon to appear in the titlebar
of a ReST application when referencing this ReST
package.info - Give additional information about the
software contained in this package.infouri
- Give a link to a text file
containing additional information about the software
contained in this package.installation
- The 4th of the 5 steps to
installing a package.installerattributes
- Contains attributes to
customize the look and feel of the ReST Installer for a
specific package.license
- Define the licensing terms of
the included software.licenseuri
- Define the licensing terms of
the included software.monitorattributes
- Contains attributes to
customize the look and feel of the ReST Monitor for a
specific package.name - Gives the name of the
packager.option
- Declares configurable options
for a command.package
- The ReST Package root
element.packagedir
- Declare a directory within the
structure of the package file.packager
- Information about the person
who created this ReST Package.packagesrc
- Declares a file that appears
in the ReST package.patch - Declares a patch file to be applied to the
sources contained in this file. (NOT CURRENTLY
SUPPORTED)pre - A set of predefined options and
substitutions.predefs
- Provide groups of pre-defined
command options and configuration
substitutions.preparation
- The 1st of the 5 steps to
installing a package.sub - Defines a substitution that will be made
in a configuration file.title - The title the will appear in the ReST
applications for this package.uninstallation
- An option additional step to
define how to uninstall a package.uri - A standard URI that may be used to provide
more information about a package or package
author.version
- Give the version of packaged
software.action — Commands that can
be run after a package has been installed.
Once a package has been installed there may be some commands that a user will be able to run. ReST calls these commands "actions" and allows them to be run in the Installer immediately after an installation or by the Explorer at any time after the package has been installed.
name (required) - How the action should be known
tooltip (required) - This will appear as a tooltip in the ReST applications
id (optional) - A unique id for this action within the package. This is only needed if there are dependencies between actions.
depends (optional) - A comma-separated list of action ids on which this action depends.
actions — Wrapper element
for multiple action elements.
Example 10. Actions Example
<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."/>
</actions>
backgroundcolor — Declare
the background color that should be used in the ReST
applications when referencing this package.
If the backgroundcolor element
appears in an application's attributes then the declared
color will be used instead of the default background
color for applications referencing this package. The
color should be given in hex notation as would be given
in HTML code.
The following elements are valid parents of backgroundcolor:
explorerattributes, installerattributes,
monitorattributes.
backgroundimage — Declare
the background image that should be used in the ReST
applications when referencing this package.
If the backgroundimage element
appears in an application's attributes then the given
image will appear as a watermark in the background of
ReST applications as they refernce this package. The
image could be included in the ReST package or reference
an image that appears in a web space.
The following elements are valid parents of backgroundimage:
explorerattributes, installerattributes,
monitorattributes.
base — Gives the base
directory for this package.
By defining a base directory for a package, multiple packages can be organized to share a common space. This is useful for organizing libraries, which can be given a base of libs, or software packages that include several plugable or optional components that may be installed at a later time.
checksumuri — Give the uri
to a file that contains the checksum for this
package.
When a package is created with the ReST packager a
checksum is printed, which can be placed in a file on a
webspace. This element points to such a file to give the
ReST application the ability to verify the package before
using it. This behavior is optional. ReST packages
already contain checksums of the files contained, which
are verified when a package is used; package checksums
are in addition to this behavior. At the current time
checksumuri is not
supported, but will be added to future versions of
ReST.
command — Run a command on
the remote system.
The command tag declares a
single command to be run on the remote system. By default
this command is run in a /bin/bash environment and commands should
be written with this in mind. A command contains 0 or
more option tags, allowing the
command to be configured from the ReST application's
GUI.
value (required) - The command to be run.
shell (optional) - The shell in which to run the
command. At this time shell is not supported, but support
will be added in future versions of ReST.
required (optional) - If the user should be
given the option to not run this command,
required should be set to
false. If required is not
given, the command will be run.
grouped (optional) - If running the command on
one machine in a given logical group is sufficient,
set grouped="true", if
grouped is not given or
grouped="false" the
command will be run on every machine in the logical
group.
id (optional) - A unique id given to this command, which is used if command dependencies exist. Dependencies are not supported at this time.
depends (optional) - A comma-separated list of ids on which this command depends. Dependencies are not supported at this time.
errormsg (optional) - A short message that should be displayed as the status of a given location if the command fails.
statusmsg (optional) - A short message that will be displayed as the status of a given location as it runs a command.
description (optional) - A description of the command, used to help users understand the commands as they are configured.
forceConfigure (optional) - By default command
options are only configured in Advanced Mode for a
given ReST application. However, if a given command
must be
configured, set forceConfigure="true".
The following elements are valid parents of command: action, compilation, completion, configuration, installation, preparation, uninstallation.
Example 11. Command Example
<command value="make" grouped="true"> <option type="boolean" truevalue="standard" name="Standard" enabled="true"/> <option type="boolean" truevalue="all" name="All"/> <option type="boolean" truevalue="server" name="Server"/> <option type="boolean" truevalue="agent" name="Agent"/> <option type="boolean" truevalue="C" name="C"/> <option type="boolean" truevalue="Fortran" name="Fortran"/> <option type="boolean" truevalue="matlab" name="Matlab"/> <option type="boolean" truevalue="octave" name="Octave"/> <option type="boolean" truevalue="mathematica" name="Mathematica"/> <option type="boolean" truevalue="gridrpc" name="GridRPC"/> <option type="boolean" truevalue="pdfgui" name="PDF Gui"/> <option type="boolean" truevalue="tools" name="Tools"/> <option type="boolean" truevalue="wrappers" name="Wrappers"/> <option type="boolean" truevalue="tester" name="Tester"/> <option type="boolean" truevalue="regress" name="Regression Test Suite"/> <option type="boolean" truevalue="clean" name="Clean"/> <option type="boolean" truevalue="configclean" name="Configclean"/> <option type="boolean" truevalue="CLEAN" name="Clean every architecture"/> </command>
compilation — The 3rd of the
5 steps to installing a package.
completion — The 5th of the
5 steps to installing a package.
configfile — Declare a file
that must be configured by the user.
A package may contain configuration files for the
packaged software. These files will be configured from
the GUI by the user. The configfile will contain several
sub tags, which define tokens
that will be replaced in the file.
packagefile (required) - The name of the file as it is contained in the package.
remotefile (required) - The name of the file as it should be on the remote system. This can be a relative pathname (ex. src/file.conf).
description (optional) - A description of the file's purpose or conventions.
forceConfigure (optional) - If forceConfigure="true" the user will
be required to edit the file, even if they are not
in Advanced Mode in the ReST application. If
forceCongfigure is not
declated or forceConfigure="false" the defaults
will be used for all substitutions.
Example 12. Configfile XML Example
<configfile packagefile="server_config"
remotefile="NetSolve-2.0/server_config"
description="NetSolve Server Configuration File">
<sub name="nproc" description="Number of processors"
default="2" type="string"/>
<sub name="agent" description="The NetSolve Agent hostname"
default="netsolve.cs.utk.edu" type="string"/>
<sub name="scratch" description="Scratch Directory"
default="/tmp/" type="string"/>
<sub name="mpihosts" description="Number of MPI Hosts"
default="4" type="string"/>
<sub name="workloadmax" description="Maximum allowable workload"
default="-1" type="string"/>
</configfile>
configuration — The 2nd of
the 5 steps to installing a package.
This is the 2nd of the 5 steps to installing a
package, occuring after preparation and before
compilation. Commands that relate to configuration for
compilation (such as running configure scripts) should be done in this
step. Configuration files are sent to the remote location
immediately before this step.
This element is used to define a command option (if
type="option") or substitution (if type="sub") within a
pre set. See predefs for a usage
example.
description — Provide a
description of the package.
explorerattributes —
Contains attributes to customize the look and feel of the
ReST Explorer for a specific package.
Contains attributes to customize the look and feel of the ReST Explorer for a specific package.
The following elements are children of explorerattributes:
backgroundcolor, backgroundimage, icon.
header — Provide basic
metadata about the package.
The following elements are children of header: action, actions, checksumuri, configfile, description, explorerattributes, info, infouri, license, licenseuri, monitorattributes, name, packagedir, packager, packagesrc, patch, predefs, title, packager, packager.
Example 14. Package Header Example
<header>
<name>NetSolve</name>
<title>NetSolve Installer</title>
<version>2.0</version>
<description>NetSolve is a grid middleware package</description>
<uri>http://icl.cs.utk.edu/netsolve/</uri>
<!-- Basic information about the packager -->
<packager>
<name>Jeff M. Larkin</name>
<uri>mailto:larkin@cs.utk.edu</uri>
</packager>
<actions>
<action name="Start Server" tooltip="Start a NetSolve server.">
<command value="/bin/bash ./start_server.sh" statusmsg="Starting Server"
errormsg="Failed to start server."/>
</action>
<action name="Kill Server" tooltip="Kill a NetSolve server.">
<command value="/bin/bash ./kill_server.sh" statusmsg="Killing Server"
errormsg="Failed to kill server."/>
</action>
</action>
</actions>
<configfile packagefile="server_config"
remotefile="NetSolve-2.0/server_config"
description="NetSolve Server Configuration File">
<sub name="nproc" description="Number of processors"
default="2" type="string"/>
<sub name="agent" description="The NetSolve Agent hostname"
default="netsolve.cs.utk.edu" type="string"/>
<sub name="scratch" description="Scratch Directory"
default="/tmp/" type="string"/>
<sub name="mpihosts" description="Number of MPI Hosts"
default="4" type="string"/>
<sub name="workloadmax" description="Maximum allowable workload"
default="-1" type="string"/>
</configfile>
<!-- Package source(s). We can do both remote and local files -->
<packagesrc>NetSolve-2.0.tgz</packagesrc>
<packagesrc>config.guess</packagesrc>
<packagesrc>start_server.sh</packagesrc>
<packagesrc>kill_server.sh</packagesrc>
<installerattributes>
<backgroundimage>http://www.cs.utk.edu/~meek/icl/GSAP/netsolve_bg.png</backgroundimage>
<icon>http://icl.cs.utk.edu/favicon.ico</icon>
</installerattributes>
</header>
icon — Defines the icon to
appear in the titlebar of a ReST application when
referencing this ReST package.
If icon is given in explorerattributes,
installerattributes,
monitorattributes and icon
will appear in the titlebar of the related ReST
application when referencing this package.
The following elements are valid parents of icon: explorerattributes, installerattributes,
monitorattributes.
info — Give additional
information about the software contained in this
package.
infouri — Give a link to a
text file containing additional information about the
software contained in this package.
installation — The 4th of
the 5 steps to installing a package.
installerattributes —
Contains attributes to customize the look and feel of the
ReST Installer for a specific package.
Contains attributes to customize the look and feel of the ReST Installer for a specific package.
The following elements are children of installerattributes:
backgroundcolor, backgroundimage, icon.
license — Define the
licensing terms of the included software.
License and licenseuri give the packager a way to provide licensing information about the enclosed software. License elements should contain the text of the license while Licenseuri is simply a link to a text file containing the license. If Licenseuri is used, the ReST application will retrieve the license file and display its contents. Both elements are optional.
licenseuri — Define the
licensing terms of the included software.
License and licenseuri give the packager a way to provide licensing information about the enclosed software. License elements should contain the text of the license while Licenseuri is simply a link to a text file containing the license. If Licenseuri is used, the ReST application will retrieve the license file and display its contents. Both elements are optional.
monitorattributes — Contains
attributes to customize the look and feel of the ReST
Monitor for a specific package.
Contains attributes to customize the look and feel of the ReST Monitor for a specific package.
The following elements are children of monitorattributes:
backgroundcolor, backgroundimage, icon.
name — Gives the name of the
packager.
option — Declares
configurable options for a command.
Some commands may be configurable through command-line
options. Using one or more option tags within and
command allows users to customize these options via the
ReST GUI.
name (required) - The name to appear by the option during customization.
default (required) - The default value for this option. This is appended to the command after the truevalue (if type is not boolean. This may be an empty string.
type (required) - What type of substitution is this? Valid types are string (one line of text), choice (chosen from a list), boolean (true/false).
truevalue (required) - If type=boolean, this is the value to to append to the command. If type is not boolean then this will be appended to the command before the value input from the user. This can be an empty string.
falsevalue (required only if type=boolean) - The value to append if type is boolean and false is selected. This can be an empty string.
choices (required if type=choice) - A comma separated list of possbile choices for this option.
customChoice (optional) - If the type is choice and this attribute is set to true then the user may choose from the list of choices or give their own value for this option. If this attribute is false or not declared, the user is restricted to the given choices.
id (optional) - A unique id given to this option, which is used if option dependencies exist. Dependencies are not supported at this time.
depends (optional) - A comma-separated list of ids on which this option depends. Dependencies are not supported at this time.
enabled (optional) - If true this option will be turned on by default. If false or missing this option will be turned off by default.
description (optional) - A description of what this option does to the command.
package — The ReST Package
root element.
version (optional) - The version of this package. This does not necessarily match the version of the software contained in the package.
The following elements are children of package: compilation, completion, configuration, header, installation, preparation, uninstallation.
packagedir — Declare a
directory within the structure of the package file.
If the packager wishes to create a package that
contains a directory structure, rather than a flat
package, each directory inside the package must be
declared with a packagedir tag.
packager — Information about
the person who created this ReST Package.
packagesrc — Declares a file
that appears in the ReST package.
Every file that is contained in a package must be
declared with a packagesrc tag, configfile tag, or a
patch tag (but not multiple
tags). Any other file that is contained in the package
will be ignored.
patch — Declares a patch
file to be applied to the sources contained in this file.
(NOT CURRENTLY SUPPORTED)
If the sources contained in this package need to be
patched, a patch file can be included in the package and
declared with a patch tag. The specifics of
this patch file have not yet been determined and this tag
is not yet supported by ReST.
pre — A set of predefined
options and substitutions.
The pre set gives developers a
way to pre-define certain options and substitution cases
for common installations. For example, if certain options
are suggested when installing on x86 Linux, a pre set may be defined
for x86 Linux installations. See predefs for a usage
example.
predefs — Provide groups of
pre-defined command options and configuration
substitutions.
When the developer wishes to pre-define certain
options and configuration substitutions to help users by
simplifying package configuration, the predefs group is used.
These sets allow the user to suggest certain options and
substitutions for common installation cases. For example,
the developer may define pre-defined sets for x86 Linux
and Solaris.
preparation — The 1st of the
5 steps to installing a package.
sub — Defines a substitution
that will be made in a configuration file.
This element maps a substitution in a configuration
file. This substitution is only relevant to the file
defined by the parent configfile tag.
name (required) - The token that will be substituted in the file. This token should not contain any spaces or special characters.
description (recommended) - A description of what this particular substitution does in the configuration file.
format (optional) - This parameter is used to validate that the input is of the proper form. This is not currently supported by ReST.
default (required) - The default value is this substitution is not customized.
type (required) - What type of substitution is this? Valid types are string (one line of text), option (chosen from a list), text (multiple lines of text), boolean (true/false).
truevalue (required if type=boolean) - The value to subsitute if type is boolean and true is selected. This can contain an empty string.
falsevalue (required if type=boolean) - The value to subsitute if type is boolean and false is selected. This can contain an empty string.
choices (required if type=choice) - A comma separated list of possbile choices for this substitution.
customChoice (optional) - If the type is choice and this attribute is set to true then the user may choose from the list of options or give their own value for this substitution. If this attribute is false or not declared, the user is restricted to the given choices.
title — The title the will
appear in the ReST applications for this package.
The title the will appear in the ReST applications for this package. If the title is longer than 32 characters long (including spaces), an additional short title should be provided.
uninstallation — An option
additional step to define how to uninstall a package.
uri — A standard URI that
may be used to provide more information about a package
or package author.
version — Give the version
of packaged software.
Table of Contents
Complete Package XML Example — Show the complete XML of a package.
Example 18. Example Package XML
<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://icl.cs.utk.edu/ReST/Package/1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://icl.cs.utk.edu/ReST/Package/1.0
http://icl.cs.utk.edu/rest/restpackage-1_0.xsd">
<!-- Basic information about the software package -->
<header>
<title>NetSolve Installer</title>
<base>NetSolve</base>
<version>2.0</version>
<description>NetSolve is a grid middleware package</description>
<uri>http://icl.cs.utk.edu/netsolve/</uri>
<!-- Basic information about the packager -->
<packager>
<name>Jeff M. Larkin</name>
<uri>mailto:larkin@cs.utk.edu</uri>
</packager>
<actions>
<action name="Start Server" tooltip="Start a NetSolve server.">
<command value="/bin/bash ./start_server.sh" statusmsg="Starting Server"
errormsg="Failed to start server."/>
</action>
<action name="Kill Server" tooltip="Kill a NetSolve server.">
<command value="/bin/bash ./kill_server.sh" statusmsg="Killing Server"
errormsg="Failed to kill server."/>
</action>
<action name="Restart Server" tooltip="Restart a NetSolve 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>
<action name="Start Agent" tooltip="Start a NetSolve Agent.">
<command value="/bin/bash ./start_agent.sh" statusmsg="Starting Agent"
errormsg="Failed to start Agent"/>
</action>
<action name="Kill Agent" tooltip="Kill a NetSolve Agent.">
<command value="/bin/bash ./kill_agent.sh" statusmsg="Killing Agent"
errormsg="Failed to kill Agent"/>
</action>
<action name="Restart Agent" tooltip="Restart a NetSolve Agent.">
<command value="/bin/bash ./kill_agent.sh" statusmsg="Killing Agent"
errormsg="Failed to kill Agent"/>
<command value="/bin/bash ./start_agent.sh" statusmsg="Starting Agent"
errormsg="Failed to start Agent"/>
</action>
</actions>
<configfile packagefile="server_config"
remotefile="NetSolve-2.0/server_config"
description="NetSolve Server Configuration File">
<sub name="nproc" description="Number of processors"
default="2" type="string"/>
<sub name="agent" description="The NetSolve Agent hostname"
default="netsolve.cs.utk.edu" type="string"/>
<sub name="scratch" description="Scratch Directory"
default="/tmp/" type="string"/>
<sub name="mpihosts" description="Number of MPI Hosts"
default="4" type="string"/>
<sub name="workloadmax" description="Maximum allowable workload"
default="-1" type="string"/>
<sub name="testing" description="Testing PDF"
truevalue="" falsevalue="#" type="boolean" default="true"/>
<sub name="qsort" description="QuickSort PDF"
truevalue="" falsevalue="#" type="boolean" default="true"/>
<sub name="area" description="Area PDF"
truevalue="" falsevalue="#" type="boolean" default="true"/>
<sub name="mandelbrot" description="Mandelbrot PDF"
truevalue="" falsevalue="#" type="boolean" default="true"/>
<sub name="blas_subset" description="BLAS Subset PDF"
truevalue="" falsevalue="#" type="boolean" default="true"/>
<sub name="lapack_subset" description="LAPACK Subset PDF"
truevalue="" falsevalue="#" type="boolean" default="true"/>
<sub name="lapack" description="LAPACK PDF"
truevalue="" falsevalue="#" type="boolean" default="false"/>
<sub name="lapack_extended" description="LAPACK Extended Drivers PDF"
truevalue="" falsevalue="#" type="boolean" default="false"/>
<sub name="scalapack" description="SCALAPACK PDF"
truevalue="" falsevalue="#" type="boolean" default="false"/>
<sub name="sparse_iterative_solve" description="Sparse Iterative Solvers PDF"
truevalue="" falsevalue="#" type="boolean" default="false"/>
<sub name="sparse_direct_solve" description="Sparse Direct Solvers PDF"
truevalue="" falsevalue="#" type="boolean" default="false"/>
<sub name="arpack" description="ARPACK PDF"
truevalue="" falsevalue="#" type="boolean" default="false"/>
<sub name="testingglobus" description="Globus Testing PDF"
truevalue="" falsevalue="#" type="boolean" default="false"/>
<sub name="restrictions" description="Maximum allowable workload"
default="" type="text">* 10</sub>
</configfile>
<configfile packagefile="MPImachines"
remotefile="NetSolve-2.0/MPImachines"
description="NetSolve MPI Hosts File">
<sub name="hosts" description="List of MPI Hosts" type="text" default="">
enterprise
enterprise
enterprise
enterprise
</sub>
</configfile>
<configfile packagefile="netsolve.env"
remotefile="netsolve.env"
description="NetSolve Environment Variables">
<sub name="agent" description="NetSolve Agent"
default="netsolve.cs.utk.edu" type="string"/>
</configfile>
<!-- Package source(s). We can do both remote and local files -->
<packagesrc>NetSolve-2.0.tgz</packagesrc>
<packagesrc>config.guess</packagesrc>
<packagesrc>start_server.sh</packagesrc>
<packagesrc>start_agent.sh</packagesrc>
<packagesrc>kill_agent.sh</packagesrc>
<packagesrc>kill_server.sh</packagesrc>
<installerattributes>
<backgroundimage>http://www.cs.utk.edu/~meek/icl/GSAP/netsolve_bg.png</backgroundimage>
<icon>http://icl.cs.utk.edu/favicon.ico</icon>
</installerattributes>
</header>
<!-- Things to do before anything else -->
<preparation>
<command value="gunzip -f NetSolve-2.0.tgz" grouped="true"/>
<command value="tar -xf NetSolve-2.0.tar" grouped="true"/>
<command value="cd NetSolve-2.0/" grouped="false"/>
</preparation>
<!-- Configuration of the package before compilation -->
<configuration>
<!-- This is the configure line -->
<command value="./configure" grouped="true">
<!-- One of the possible configure options -->
<option name="lapack" type="text" default="/usr/local/lib/libpack.a"
truevalue="--with-lapack="/>
<option name="blas" type="text" default="/usr/local/lib/libblas.a"
truevalue="--with-blaslib="/>
<option name="petsc" type="text" default=""
truevalue="--with-petsc="/>
<option name="petsclibdir" type="text" default=""
truevalue="--with-petsclibdir="/>
<option name="aztec" type="text" default=""
truevalue="--with-aztec="/>
<option name="azteclib" type="text" default=""
truevalue="--with-azteclib="/>
<option name="superlu" type="text" default=""
truevalue="--with-superlu="/>
<option name="superlulib" type="text" default=""
truevalue="--with-superlulib="/>
<option name="ma28" type="boolean" default="false"
truevalue="--with-ma28"/>
<option name="itpack" type="boolean" default="false"
truevalue="--with-itpack"/>
<option name="arpacklib" type="text" default=""
truevalue="--with-arpacklib="/>
<option name="mpi" type="text" default=""
truevalue="--with-mpi=" falsevalue="--without-mpi"/>
<option name="scalapack" type="text" default=""
truevalue="--with-scalapacklib="/>
<option name="blacslib" type="text" default=""
truevalue="--with-blacslib="/>
<option name="mldk" type="text" default=""
truevalue="--with-mldk="/>
<option name="rpclib" type="text" default=""
truevalue="--with-rpclib="/>
<option name="rpcinc" type="text" default=""
truevalue="--with-rpcinc="/>
<option name="octave-include" type="text" default=""
truevalue="--with-octave-include="/>
<option name="gpg" type="text" default="/usr/bin/gpg"
truevalue="--with-gpg=" falsevalue="--without-gpg"/>
<option name="buildgpg" type="text" default=""
truevalue="--with-buildgpg="/>
<option name="nws" type="text" default=""
truevalue="--with-nws="/>
<option name="ibp" type="text" default=""
truevalue="--with-ibp="/>
<option name="kerberos" type="text" default=""
truevalue="--with-kerberos"/>
<option name="proxy" type="choice" choices="nestolve,globus" default=""
truevalue="--with-proxy "/>
<option name="ouputlevel" type="choice" choices="debug,view,none" default="none"
truevalue="--with-outputlevel "/>
<option name="infoserver" type="text" default=""
truevalue="--enable-infoserver"/>
</command>
</configuration>
<!-- Source Compilation -->
<compilation>
<command value="make" grouped="true">
<option type="boolean" truevalue="standard" name="Standard" enabled="true"/>
<option type="boolean" truevalue="all" name="All"/>
<option type="boolean" truevalue="server" name="Server"/>
<option type="boolean" truevalue="agent" name="Agent"/>
<option type="boolean" truevalue="C" name="C"/>
<option type="boolean" truevalue="Fortran" name="Fortran"/>
<option type="boolean" truevalue="matlab" name="Matlab"/>
<option type="boolean" truevalue="octave" name="Octave"/>
<option type="boolean" truevalue="mathematica" name="Mathematica"/>
<option type="boolean" truevalue="gridrpc" name="GridRPC"/>
<option type="boolean" truevalue="pdfgui" name="PDF Gui"/>
<option type="boolean" truevalue="tools" name="Tools"/>
<option type="boolean" truevalue="wrappers" name="Wrappers"/>
<option type="boolean" truevalue="tester" name="Tester"/>
<option type="boolean" truevalue="regress" name="Regression Test Suite"/>
<option type="boolean" truevalue="clean" name="Clean"/>
<option type="boolean" truevalue="configclean" name="Configclean"/>
<option type="boolean" truevalue="CLEAN" name="Clean every architecture"/>
</command>
</compilation>
<!-- Package Installation -->
<installation>
<!--<command value="make install"/>-->
</installation>
<!-- Clean-up what is no longer needed -->
<completion>
<command value="cd ../"/>
<command value="rm -rf NetSolve-2.0.tar" grouped="true"/>
<command value="rm -rf NetSolve-2.0.tgz" grouped="true"/>
</completion>
</package>