Permalink
Fetching contributors…
Cannot retrieve contributors at this time
1208 lines (903 sloc) 54.6 KB
The setup XML specification has the following format:
-----
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<install>
one or more install options
</install>
----
An example product specification file is at the bottom of this document.
The XML file should be a well-formed Unicode file (UTF-8), especially if you
intend to use internationalization features and non-ASCII character sets.
The INSTALL element:
The install element contains one or more OPTION elements specifying
different install options.
All attribute names are case-sensitive, and are lower-case.
There are several required attributes of the install element:
product This is used as the product name and as the default top-level
install directory name.
desc This is used a product description string, and is used in
strings naming the product (title bar, icon description, etc.)
version This is the product version string
There are several optional attributes of the install element:
path This contains the default directory which will contain the
product installation directory. The installation directory
may be changed by the user at installation time.
The default is: /usr/local/games
binarypath This can be used to specify the default binary directory (where
symbolic links to the binaries will be installed), instead of the
first writable entry in the user's $PATH. The action is very similar
to the -b command line argument to setup, and is secondary to it.
preinstall This is a shell script which is executed before any options
are installed. It is run with the installation destination
as a command line argument.
postinstall
This is a shell script which is executed after all options
are installed. It is run with the installation destination
as a command line argument.
Both the preinstall and postinstall scripts are run with
some default environment variables set. Look at the 'SCRIPT'
section below for a detailed list.
preuninstall
This is a shell script which is executed at the very beginning
of the uninstall process. It will be run before any RPM uninstall
scripts. This file is not installed, but is added to the
beginning of uninstall script.
postuninstall
This is a shell script which is executed at the very end of the
uninstall process. It will be run after any RPM uninstall
scripts. This file is not installed, but is added to the
end of the uninstall script.
IMPORTANT: An actual file name for a shell scripts needs to be specified,
not a command, for both pre/postuninstall entries.
"sh script.sh" is incorrect, but "script.sh" is correct.
Both the preuninstall and postuninstall scripts will have access
to the default environment variables. See the 'SCRIPT' section
for details.
Also, these scripts will be run at the very beginning and very
end of the install cleanup if the install is aborted.
eula This is a file which contains a text license agreement that
must be agreed to by the user before the installation will
proceed.
*OBSOLETE* DO NOT USE! Starting from version 1.3.0, use the
EULA element instead (see below).
readme This is the README file for the product, the user will be
prompted to see it before the installation begins. The default
value is "README" if not specified and such a file is
actually present.
*OBSOLETE* DO NOT USE! Starting from version 1.3.0, use the
README element instead (see below).
splash Use this tag to specify an alternate splash image (displayed to
the left of the installer in X11). The image must be in XPM format,
and the default name for this attribute is "splash.xpm".
splashpos This option sets the position that the splash image
will appear on the setup screen. If unspecified, the default is
"left". The only valid options currently are "left" and "top".
url This is a web site which is launched after the install is
completed.
update_url This is the location where updates for this product can be
fetched from.
localurl This is the local HTML file that is loaded if the network
is down, or the web site cannot be reached. It should be
specified as a path relative to the setup working directory.
This is a secondary URL, and should not be specified without
also specifying a primary URL in the "url" attribute.
auto_url This is a flag which tells whether or not to automatically
launch the web browser on the product URL. It can be either
"true" to launch the browser, or "false" to prompt the user.
The default behavior is to prompt the user as to whether or
not to launch the web browser.
cdrom If this attribute has the value "required", then setup will
prompt the user asking them to mount the product CDROM.
*NEW* : The 'cdromfile' attribute must also be set.
cdromfile This is a (now mandatory) unique file that is looked for on the
mounted CDROM to see if it is indeed the product CDROM.
This attribute must always be set if the 'cdrom' attribute is used.
nouninstall This is an optional flag which, if specified, tells setup
not to generate an uninstall script after it runs. It also
doesn't generate any data for product queries and auto-updating.
uninstall This attribute is used to change the name of the generated
'uninstall' script. If not used, the script will always be
named 'uninstall', which can be a problem if you need to
install different products in the same directory.
*THIS ATTRIBUTE IS DEPRECATED AS OF SETUP 1.5.0*
nobinaries When set to "yes", then setup won't prompt the user for a
path for binaries. Set this when this installation won't
actually install any binary file.
*THIS ATTRIBUTE IS DEPRECATED AS OF SETUP 1.6.2*
Not putting a 'binary' tag in the XML file will have the same effect.
promptbinaries When set to "yes", setup will create a checkbox
to allow the user whether or not to create
a symbolic link to the binaries.
This setting has no effect if nobinaries is "yes".
fork If set to "yes", and a binary can be started upon successful installation,
setup will fork() itself, allowing the installer to exit as the program is
running. Note: this may cause problems removing setup binaries within setup.sh
on some platforms.
meta When this attribute is set to "yes", then setup will act as
a meta-installer, i.e. it will allow the user to select a
product and set-up will respawn itself for the selected
product installation.
See the section "About Meta-Installation" below.
component When this attribute is present, its value is the name of the component
that will created by this installer. This means that the files will be added
to an existing installation of the product, and that basic configuration parameters
such as the installation path will be used from the previous installation.
Currently setup is not able to update an existing component, thus if the component
is detected as already installed the installation will fail.
Important: This attribute can't be mixed with <component> elements.
superuser If set to 'yes', then the installer will refuse to start if not run as
the super-user (root).
(CARBON ONLY) This option causes the installer to prompt the user for
appropriate credentials. This is a standard thing for Mac and should
typically be done instead of "running as root".
express If set to 'yes', then the user will have the choice between "Recommended" and
"Expert" classes of installation. "Expert" is the normal mode, when the user has to confirm
all steps of the installation. "Recommended" uses the defaults values and proceeds to the
installation automatically with as less input from the user as possible.
once If set to 'yes', the installer won't allow to install the same product twice, and will ask
the user to uninstall manually a previous instance if it could be detected.
reinstall If set to 'yes', the install will allow the product to be reinstalled. The default behavior
is not to let the user install product options twice.
reinstallnowarning If set to 'no' (the default), the install will warn the user
that a reinstall is about to occur.
reinstallfast If set to 'yes' and this run is a reinstall, the installer will skip the options
screen and go directly to installation. This is good for automatic updates of
previously-installed software. Unless explicitly disabled (see eula's
ignoreonreinstall option), license agreements still need to be explicitly agreed
to before the reinstall can proceed. You still need to set several other options
in the install tag to get a fully automatic reinstall (reinstallnowarning,
nopromptoverwrite, etc).
appbundle (CARBON ONLY) If this is "yes", the destination folder does not include the product
name as part of the path. An application bundle is typically installed much like
a single file would be...and so is treated as such.
The app bundle path usually specified in the "path" attribute of the "files" element,
or it is specified in the archives directly.
category Indicates the product category, used to specify the menu entry on some systems. Defaults
to "Games"
manpages If set to "yes", then the user will be prompted for the install pages installation path.
Should be used when using the MANPAGE element described below.
nopromptoverwrite If set to 'yes' existing files will be overwritten without
prompting the user. This was the default before setup 1.6.4
nomenuitems If set to 'yes', menu items for Gnome/KDE/etc will not be installed, and the
user will not be prompted about installing them.
appbundleid (CARBON ONLY) This string means that you are installing new files into an existing
Application Bundle. If the bundle isn't found, the installation aborts, otherwise, all
files are added relative to the base of the app bundle. The string specified here is
the app bundle's CFBundleIdentifier entry in its Info.plist file. LaunchServices are
used to find the bundle and the user can be prompted to manually locate the product
if LaunchServices fails to find it. This is all MacOS-specific, and unrelated to the
"component" attribute.
appbundledesc (CARBON ONLY) This string is used with the "appbundleid" attribute...it's a human
readable text describing the app bundle in question.
requireosx (CARBON ONLY) This string specifies the minimum version of Mac OS X
that must be installed on the system for the product to be installed.
The CDROM element:
An installer can fetch the necesary data files from one or more CDROM discs. As of setup 1.5.0,
each available CDROM must be described through a <cdrom> element, and the 'cdromid' attributes
of the <binary> and <files> elements.
This element takes two mandatory attributes :
id An unique identifier that will be used to reference this CDROM in other elements.
name A string describing the CDROM, intended to be prompted to the user.
The file name given in the CDROM element is the path to a unique file on the described CDROM that
will be used to identify the media. Here is an example :
<cdrom id="cd1" name="Disc Number One">cdrom1.dat</cdrom>
<cdrom id="cd2" name="Disc Number Two">cdrom2.dat</cdrom>
This describes two CDROMs, and the presence of one of the .dat files at the root of each CDROM will
identify which CDROM is which.
Hint: To avoid useless CD prompts to the user, when using a multiple CDROM installer you should always
specify the size of the files in the XML file directly. This way the user won't have to swap CDs when
the installer is trying to compute the total size of the options.
The user can define at runtime the path to CD images by using the environment variables
SETUP_CDROM_xxx, where xxx is the upper-case ID for the CDROM, i.e. SETUP_CDROM_CD1 for the
first CD of the above example. The SETUP_CDROM environment variable can also be used and it will
be used to match all CDROMs, if you can have all CD images under the same directory.
The COMPONENT element:
Components are used to divide the product in independant entities. Several components can be
installed at the same time by setup, and the user interface will reflect that. The installation
options have to be structured as children of this element.
Please note that components can not be nested. Thus COMPONENT elements have to be direct children
of an INSTALL element.
This element takes two mandatory attributes :
name The name of the component.
version A string describing the version of the component.
There are also optional attributes :
default If 'yes' then the component is marked as being the default component, i.e. the main
component for the product. It has to be defined in one of the components.
showname If 'yes' then the component name will be displayed in the user interface.
arch This component is only available on the specified architectures.
The architecture can be any of:
x86, ppc, alpha, sparc64, etc.
libc This component is only available with the specified version of libC.
The version can be one of:
libc5, glibc-2.0, glibc-2.1, etc.
distro This component is only available with the specified OS distribution.
Look at the end of this file for a list of possible values.
if Specify an expression that has to be satisfied. See the BOOL element for more details.
preuninstall The path to an optional pre-uninstall script for the component.
postuninstall The path to an optional post-uninstall script for the component.
The README and EULA elements:
Those elements are used to mark special files, that are unique for
each program and are always installed in the installation directory.
Those are of course optional. The README tag specifies the program's
README file. The EULA should specify the End-User License Agreement or
license associated with the program, and it will be the first thing
that the user will be prompted with.
Both elements accept these optional attributes :
lang Specify a locale, so that you can have different EULAs and
READMEs translated in many languages in the same distribution.
See 'About localization' below for more details.
keepdirs By default, the file will be copied to the root of the installation
directory. If set to yes, then you can specify a relative path for the
file, and have it installed in a sub-directory.
ignoreonreinstall If set, when reinstalling, the EULA window will be skipped,
as if the user accepted the agreement.
The important thing to remember about those elements is that they are
siblings of the OPTION element described below, and thus direct children
of the INSTALL element. The README elements should NOT be inside an OPTION
element, alongside 'file' and 'binary' elements.
Starting with version 1.6.1, EULA elements CAN be specified for each option
as sub-elements of an OPTION tag. The syntax is identical to global EULA tags.
You may not want to combine multiple EULAs with an "Express" installer, as this
would currently allow the licensing agreements to be bypassed by the user.
There is also no need to have the files designated by those tags explicitly
installed in a FILES section, setup will take care of that for you.
The ENVIRONMENT element :
This element is used to preserve some environment variables between Setup tools
sessions. This is useful if some features of your product can be selected through
such environment variables upon installation, and these need to be set for
uninstallation as well.
You can use this element to inform Setup that their value upon installation must
be saved in the product database. The value will be restored in the environment
before executing any scripts from any of the Setup tools (especially uninstall).
This element should be a direct child of an INSTALL or COMPONENT element.
Hence, there can be component-specific variables. Setup tools will first restore
the global product variables, and then the component-specific variable.
Note: the variable will be saved only if it is set to a non-empty value at the
time of installation.
This element takes one mandatory attribute :
var The name of the environment variable to save.
The BOOL element :
This element allows the user to create some complex expressions to guide the
installer. This element allows the user to define boolean conditions, the values of
which are defined by arbritrary scripts. These booleans can then be used as part
of expressions used by other elements, like FILE or BINARY below, to define conditions.
This element must be a direct child of the root INSTALL element. Booleans are global
to a particular instance of the installer. Additionally, the installer itself defines
a set of standard booleans, as described below.
Booleans are intended to replace the previous filtering mechanisms, using "arch", "libc"
and so on attributes, while providing additional flexibility.
Booleans are case sensitive.
The BOOL element takes one mandatory attribute :
name The symbolic name for the boolean (variable name). May be up to 30 characters
long, and must start with an alphanumerical character. May not contain blank
spaces.
Additionally, one of the following attributes must be used, unless "if" below is in use :
script The command to be run to determine the value of the boolean. In the UNIX
tradition, it should return 0 for a TRUE value.
envvar The name of an environment variable to query for the value of the boolean.
The value must be a non-zero number to map to be TRUE. If the variable is not
set in the environment, the boolean will likewise be set to FALSE.
setenv The name of an environment variable that will be set with the value of the boolean
when running user scripts throughout the installer. The value of that variable will
be 0 or 1. This can be used for advanced scripting querying the internal state of
the installer.
It also recognizes two optional attributes :
later If set to "yes", the script will be executed at the time that the condition
referencing it is evaluated. The default is to run the script once immediately
upon initialization to gather the static value.
if Additionally make this boolean dependent on another boolean expression. This
expression can reference any previously defined boolean. See below for more details
about the syntax. If this expression evaluates to FALSE, then the script won't be
run, or the environment queried, and the value will also be set to FALSE.
Note: if neither "script" or "envvar" are set for the element, the value will be set
to true if the condition is satisfied.
Standard booleans defined by the installer :
- Standard 'true' and 'false' booleans.
- 'is-root' is TRUE if the installer is running as root.
- 'reinstalling' is TRUE if the product is already installed.
- 'bzip2' is TRUE if Bzip2 decompression is available in the installer.
- One boolean corresponding to the selected user interface: gtk1, gtk2, carbon, dialog, console
- One boolean for the CPU architecture: x86, ppc, sparc, alpha, etc
- One boolean for the detected libc version: libc5, glibc-2.1, etc.
- One boolean for the distribution / OS name : redhat, suse, aix, sco, etc.
- A boolean for the OS name as returned by uname.
- Two booleans representing the detection distribution version (not always meaningful) :
distro-major-<number> and distro-minor-<number>.
= Booleans for the detected locale setting and its encoding, e.g. en_US, ISO-8859-1, etc.
- On Linux, 'selinux' indicates whether SELinux is available and enabled.
- If RPM support was compiled in, 'rpm-support' is set. If RPM 3.x, then 'rpm3-support' is
also set to TRUE.
For example, on a Redhat Linux 7.3 sytem, the following bools would be defined to TRUE :
Linux, x86, redhat, distro-major-7, distro-minor-3
For more information about how to write expressions referencing these booleans, refer
to "About Boolean Expressions" below.
The REQUIRE element :
This element allows to set prerequisite conditions for the installer, through the
use of arbitrary commands whose return value is used to determine whether the conditions
are fulfilled.
'require' elements have to be at the top level (right under the root 'install' element), and
are parsed in sequential order. Installation will abort if any of the specified commands return
a non-nil value, unless the 'warn' attribute is set.
This element takes either of the following mandatory attributes :
command Specify the command to be run to determine the condition. A nil value means success.
feature Specify the name of a feature that must be present in the
installer to be able to process this XML file.
condition Specify an expression that has to be satisfied. See the BOOL element for more details.
This element takes some optional attributes :
lang Specify the language for the message. Used for localization. The command will be executed
only if the locale settings match.
arch This requirement applies only on the specified architectures.
The architecture can be any of:
x86, ppc, alpha, sparc64, etc.
libc This requirement applies only to the specified version of libc.
The version can be one of:
libc5, glibc-2.0, glibc-2.1, etc.
distro This component applies only to the specified OS distribution.
Look at the end of this file for a list of possible values.
version [only for feature attribute] the minimum integer version number
required for the specified feature.
warn If set to 'yes', then the user will only be displayed the message as a warning and the
installation may continue regardless.
The text specified in the element will be displayed to the user if the
condition of the command attribute fails. It has no meaning for the feature
attribute.
Examples:
<require command="/bin/false">
This is always failing! Thus this message is always displayed.
</require>
<require condition="Linux">
You need Linux for this installer!
</require>
<require feature="inline-scripts" version="1"/>
The POST_INSTALL_MSG element :
This element displays an optional message to the user at the end of a successful installation.
Whether this message is displayed or not can be conditionned by an external command.
This element takes some optional attributes :
lang Specify the language for the message. Used for localization. The message will be showed
only if the locale settings match.
command A shell commands whose return value will determine whether to display the message.
A return value of 0 must be returned for the message to be displayed.
if Specify an expression that has to be satisfied. See the BOOL element for more details.
nogui If set to 'true', then the message will not be displayed in a GUI environment (X11, Mac)
The REMOVE_MSG element :
This element is used to prompt the user in the Uninstaller tool with a message upon uninstalling
the component. The user can then choose to abort the uninstallation. This element is a simple
text that can be localized.
This element takes one optional attribute :
lang Specify the language for the message. Used for localization. The message will be showed
only if the locale settings match.
The INSTALL_DROP_LIST element:
The install_drop_list element makes it possible to override the default
installation paths supplied in the Installation target drop down box.
Supply a list of drop down paths, space or new line separated.
An example follows:
<install_drop_list>
/opt /usr/local
/var
~
</install_drop_list>
If no install_drop_list element is given, it will default to hard coded
values (see install.c).
Note: Your paths will not be displayed if they are not valid,
writable paths.
The PROGRAM_TO_START element:
The program_to_start element allows you to request that a given
program be started after installation, without that program having
to be a symbolic link.
That is, if you do not wish to have a symlink or primary binary,
but just wish to indicate that a certain program should be launched
at installer end, this element will allow you to do that.
You can use the $INSTALLDIR string and the installer will substitute
the path where the program was installed.
An example looks like this:
<program_to_start>
$INSTALLDIR/my_cool_binary_file
</program_to_start>
The OPTION element:
The option element contains text describing the element, along with
zero or more option, binary, files, and script elements.
There is currently no way to specify relationships of options at the
same level; each may be installed independently of any other. If
an option is dependent upon another option, it must be inside the
body of that option:
<option>
Top-level option
<lang lang="locale">Translated 'Top-level option'</lang>
<option>
First dependent option
<lang lang="locale">Translated 'First dependent option'</lang>
</option>
<option>
Second dependent option
</option>
</option>
Nested options will not be available unless the top-level option is
selected.
There are several optional attributes of the option element:
install If this attribute is set to "true", then the option will
be installed by default. It may be deselected by the user.
Another possible value is "command", in which case the script specified
in the "command" attribute will determine the final value of this
property.
Yet another possible value is "condition" , in which case the expression
specified in the "condition" tag will be evaluated instead.
command This attribute must be set to a shell script if "install" is "command".
If the command returns with a value of 0 (normal), then the option will
be selected (and unselected otherwise).
This can be used for auto-detection purposes.
condition Boolean expression to be evaluated to determine if the option will be
selected. This can also be used for auto-detection purposes.
required If this attribute is set to "true", the option will always
be installed. The user won't be able to disable it.
show If present, this attribute specifies a command to be run whose return
value will determine if this option will be presented to the user at all.
A 0 return value means that the option will be displayed.
A "false" string for this attribute will always hide the option from the user.
All suboptions are also affected by this setting. Note that default values
and actual selection of the option (with the above tags) is not affected.
showif Similar to the "show" attribute, except uses a boolean expression to evaluate
the condition.
help This attribute is a help string which is displayed to the
user if the user requests more information about the option.
This string can be translated to other languages using the 'help'
sub-element explained below.
arch This option is only available on the specified architectures.
The architecture can be any of:
x86, ppc, alpha, sparc64, etc.
libc This option is only available with the specified version of libC.
The version can be one of:
libc5, glibc-2.0, glibc-2.1, etc.
distro This option is only available with the specified OS distribution.
Look at the end of this file for a list of possible values.
if Specify an expression that has to be satisfied. See the BOOL element for more details.
size This is an optional size of the install option. The size can be
expressed in megabytes (with a M suffix), kilobytes (K), gigabytes
(G), or even bytes (B, or no suffix). Please note that versions of
setup earlier than 1.3.0 used to specify the size in MBs only.
If this element isn't specified, setup will try to autodetect
the size of the install option itself.
product If this XML file describes a meta-installation (if the 'meta' attribute
to the root install element has been specified), then the value of this
attribute is used to specify the XML file that will be passed to setup
to install the product described by this option element. This attribute
is ignored if this is not a meta-installation, and required if it is.
See the section 'About Meta-Installations' below for more details.
productdir Valid only together with the 'product' attribute. Specifies the
directory to change to before executing the installer for the new
product.
tag If specified, this string will be included in the SETUP_OPTIONTAGS
environment variable that is set before calling any scripts. This allows
scripts to know what user selections are active.
reinstall If this is a reinstallation, you can individually disable options that can
be reinstalled with this attribute set to "false".
The option element support the LANG sub-element, which is used to specify
translated strings for the option name. The only attribute of this element
is 'lang', which should be the name of the locale to be matched against
the current locale (i.e. "fr", "de", "it", etc...). See 'About localization'
below for more details about locale matching.
If you don't specify translations for alternate locales, then the same
string will be used for all languages encountered by setup. Of course,
you can have several 'lang' elements per 'option' element.
The option element also supports the HELP sub-element, which can be used
to provide translated strings for the 'help' attribute. This element
only supports the 'lang' attribute to specify the locale this translation
applies to. Here is an example to clarify all this :
<option install="true" help="You really need this">
Basic install
<help lang="fr">Vous avez besoin de cela</help>
<help lang="es">Su necesito eso</help>
...
</option>
This provides French and Spanish translations of the "You really need this"
help message. Please forgive my very poor Spanish ;-)
Starting with version 1.6.0, the OPTION element also supports the WARN sub-element.
WARN has a syntax identical to the HELP sub-element, but allows you to specify a
warning message that will be displayed to the user when the corresponding option
is selected. Just like HELP, this warning message can be translated through the use
of the 'lang' attribute.
The EXCLUSIVE element:
This special element is used to describe a set of OPTION elements that are
mutually exclusive, i.e. only one of them may be selected and installed.
Its usage is very simple; just surround the group of options with an
encompassing 'exclusive' element, as such :
<exclusive>
<option install="true">
Option A
</option>
...
<option>
Option X
</option>
</exclusive>
WARNING: You should always define a default option within the group of
exclusive options, by setting its 'install' attribute to 'true'.
The EXCLUSIVE element also supports LANG sub-elements to provide translations.
The EXCLUSIVE element has the following optional attributes :
reinstall If this is a reinstallation, and this is set to "false", then
the choices from the original installation will be preserved
and won't be modifiable by the user.
The BINARY element:
The binary element contains one or more binary files to be installed for
this option. The binary is installed in the top level of the install
directory, and if the symlink attribute is set, a symbolic link is
placed in the system executable path.
The actual file that is copied resides in bin/<os>/<arch>/<libc>/, where
"<os>" is the Operating System string (output from the 'uname -s' command),
"<arch>" is the current architecture string (x86, ppc, alpha, etc.)
and "<libc>" is an optional C library version (glibc-2.0, glibc-2.1, etc.)
For example, if you wanted to install an executable file named "foo"
on a PPC system, you would need it on the install disk as bin/Linux/ppc/foo.
If it depended upon version 2.1 of the GNU C library, you would place
it on the install disk as bin/Linux/ppc/glibc-2.1/foo.
There are several required attributes of the binary element:
arch "any" is synonymous with the current architecture. You can also
use this attribute to force a precise architecture, for example
"ppc" or "sparc64". Matching can be negated with a leading !,
for instance "!x86".
libc "any" is synonymous with the current libc version. This can
also be used to force a libc version for the binary, i.e
"glibc-2.0" or "glibc-2.1". Matching can be negated with a
leading !, for example "!glibc-2.0".
There are several optional attributes of the binary element:
distro Files are only installed with the specified OS distribution.
Look at the end of this file for a list of possible values.
if Specify an expression that has to be satisfied. See the BOOL
element for more details.
symlink This is a symbolic link that is installed in the system path
and points to the installed binary.
play If this attribute has the 'yes' value, then this is the binary
that will be used to optionally launch the game after the
installation program terminates. There can be only one 'binary'
element with this attribute in the whole XML file.
If this attribute has the 'no' value, and a 'symlink' is defined,
then this binary will explicitly not be used to launch after
the installation. The default value for this attribute is 'yes'
for the first binary with a symlink.
The value can also be 'gui', which means that the binary will only
be launched if the installer is in a graphical environment (e.g X11).
icon This is an optional icon file that you should install into
the top level of the install directory. If both a symlink
and an icon are specified for a binary, it will also have a
desktop icon or menu item created for it, if the user wishes.
menu This is an optional submenu that the application menuitem is
installed into. If no submenu is defined, the menu item will
be placed in the "Games" submenu.
name This is an optional name for the menu entry. By default the
name of the product is used.
desc This is an optional description for the menu entry. By default the
description of the product is used.
cdrom If this attribute has a "yes" value, then setup will look for
the file on one of the mounted CDROMs on the system.
*OBSOLETE in setup 1.5.0* DO NOT USE
cdromid Specifies a CDROM from which the file will be pulled.
keepdirs If this attribute has a "yes" value, then the directory structure
specified in the file names for the binaries will be kept. For
example: bin/mybin will be extracted in the 'bin' subdirectory
under the installation directory, instead of being extracted in
the installation directory itself.
lang The files are only installed if the current locale matches the
string of this attribute. See 'About localization' below for
more details.
binpath Specifies an optional directory from which the binaries will be pulled,
instead of the default "bin/<arch>/<libc>" directory.
inrpm If inrpm="true" then setup will not attempt to copy the file, but
it will assume that it was successfully installed by an RPM
package. Setup will set up the symlink and menu items for it.
For this to work, the value inside the <binary> tag should be the
installed location of the binary file. If the RPM is being
relocated to the install directory (see 'FILES' below for details)
you can use a macro $INSTALLDIR which will be expanded at runtime.
So, if you have a file that the RPM installs into [installdir]/bin
the XML would look like this:
<binary inrpm="true" symlink="app">
$INSTALLDIR/bin/app
</binary>
Note that the <files> section which contains the RPM pacakge must
appear before the <binary> tag to ensure that the file exists
before the symlink and menu items are created.
md5sum You can optionally specify a MD5 checksum string (32 characters from
the output of the 'md5sum' command), and the copied file will be verified
against this checksum. Installation will abort in the case of an invalid
checksum, indicating corruption.
mode Use an octal value to specify the permissions of the file once installed (755
is the default for binaries).
args Specify optional arguments to be added on the command line when running the binary.
inline When set to 'yes' the text content of the element is used as script
content instead of a path. The value of 'binarypath' is used as
script name in this case
The FILES element:
The files element contains a list of files and directories, one per line,
which are installed for this option.
You may specify relative paths and shell wildcard patterns for the files.
There are several optional attributes of the files element:
path This is a system path that these files should be installed into.
If the path is relative (i.e. does not begin with '/'), then it
is interpreted as being relative to the installation root for
the product. Thus an empty value ("") can be used to designate
the installation directory.
arch "any" is synonymous with the current architecture. You can also
use this attribute to force a precise architecture, for example
"ppc" or "sparc64". Matching can be negated with a leading !,
for instance "!x86".
libc "any" is synonymous with the current libc version. This can
also be used to force a libc version for the binary, i.e
"glibc-2.0" or "glibc-2.1". Matching can be negated with a
leading !, for example "!glibc-2.0".
distro Files are only installed with the specified OS distribution.
Look at the end of this file for a list of possible values.
if Specify an expression that has to be satisfied. See the BOOL
element for more details.
srcpath This is a directory relative to the top of the CD where the files
for this element should be copied from.
cdrom If this attribute has a "yes" value, then setup will look for
the files on one of the mounted CDROMs on the system.
*OBSOLETE: Do not use. Use 'cdromid' instead.*
cdromid Specifies a CDROM from which the file will be pulled.
mutable If set to "yes", then the file will be considered mutable, i.e. it
will not be considered corrupted if its checksum changes.
lang The files are only installed if the current locale matches the
string of this attribute. See 'About localization' below for
more details.
relocate If relocate="true" and an RPM package file is listed, the install
will force the RPM to be installed into the user-selected install
directory. This is equivalent to installing the RPM like this:
rpm -U --relocate /=INSTALLDIR --badreloc [rpmfile]
This will apply to all RPM files within this <files> tag.
nodeps If nodeps="true" and an RPM package file is listed,then the
--nodeps option will be added to the RPM command when the files
are installed. This will force RPM to install the package, even if
its dependencies are not met. This will apply to all RPM files
within this <files> tag.
autoremove If autoremove="true" and an RPM package file is listed in the
files section, then that RPM package will be automatically removed
("rpm -e package") when the uninstall script is run. If the
autoremove option is not set, then the uninstall script will list
the package name at the end of the uninstall, but it will not
remove it. This will apply to all RPM files within this <files>
tag.
md5sum You can optionally specify a MD5 checksum string (32 characters from
the output of the 'md5sum' command), and the copied file will be verified
against this checksum. Installation will abort in the case of an invalid
checksum, indicating corruption.
mode Use an octal value to specify the permissions of the file once installed (644
is the default for regular files).
When specifying archives handled by a plugin, the plugin may choose to use this
mode for all files uncompressed from the archive.
NOTE: This doesn't apply to directories, which are currently always created with
mode 755.
secontext On Linux systems only. Specify an optional SELinux context string that will be
applied to the files upon creation, by calling the chcon command.
suffix An optional file extension that is forced on all files. Can be used
to make loki-setup recognize e.g. SFX ZIP archives as such even if
they end in .exe.
The MANPAGE element:
If your product comes with man pages (destined to be installed system-wide), they have to be
installed under a man/man<section>/<name>.<section> directory structure inside the image.
Section and name are provided using the following mandatory attributes :
name The name of the command or function the man page refers to. Can be arbitrary.
section The section of the man pages the corresponding page belongs to.
The following attributes are optional :
symlink A comma-separated list of symbolic links to create for this man page, in the same
section. Use this when your man page covers several commands / functions.
arch "any" is synonymous with the current architecture. You can also
use this attribute to force a precise architecture, for example
"ppc" or "sparc64". Matching can be negated with a leading !,
for instance "!x86".
libc "any" is synonymous with the current libc version. This can
also be used to force a libc version for the binary, i.e
"glibc-2.0" or "glibc-2.1". Matching can be negated with a
leading !, for example "!glibc-2.0".
distro Files are only installed with the specified OS distribution.
Look at the end of this file for a list of possible values.
if Specify an expression that has to be satisfied. See the BOOL
element for more details.
Note that the MANPAGE element does not take any children.
Do not forget to set the "manpages" attribute to the root <install> element to "yes" to be able
to use this feature.
The SCRIPT element:
The script element contains shell commands which are executed when the
option is installed. You may interleave multiple script and files
elements, and they will be installed/executed in the order in which
they appear.
If you call a script on the installation medium, remember that the
medium may be mounted without executable permissions, so the script
file should be called using the name of the script interpreter.
For example:
<script>
sh setup.data/stage1.sh
</script>
There supported attributes for the script element are :
lang The script is only installed if the current locale matches the
string of this attribute. See 'About localization' below for
more details.
arch "any" is synonymous with the current architecture. You can also
use this attribute to force a precise architecture, for example
"ppc" or "sparc64". Matching can be negated with a leading !,
for instance "!x86".
libc "any" is synonymous with the current libc version. This can
also be used to force a libc version for the binary, i.e
"glibc-2.0" or "glibc-2.1". Matching can be negated with a
leading !, for example "!glibc-2.0".
distro Files are only installed with the specified OS distribution.
Look at the end of this file for a list of possible values.
if Specify an expression that has to be satisfied. See the BOOL
element for more details.
size If the script handles the installation of some files and you want
the progress bar to reflect it, indicate the size here. The size
is updated when the script finishes. The syntax of this element is the
same as for the size tag for the OPTION element.
message The message to display to the user. By default this is
"Running script"
cdromid When doing a multi-cd installation and running scripts then
SETUP_CDROMPATH may not be set as expected. To ensure that it is
set properly indicate which CD the script is executing against
if it is copying files from a CD.
It is also possible to filter the scripts on system characteristics, through
the use of the "arch", "glibc" and "distro" attributes, that work just like
for the "files" element.
The following environment variables are defined while in the shell script:
SETUP_PRODUCTNAME : Product name from the XML file
SETUP_PRODUCTVER : Product version from the XML file
SETUP_COMPONENTNAME : Name of the product component this script belongs to
SETUP_COMPONENTVER : Version of the product component
SETUP_INSTALLPATH : Installation path of the data files
SETUP_SYMLINKSPATH : Path where symbolic links for the binary files
will be placed.
SETUP_CDROMPATH : Path where the install CD-ROM is mounted, if
the XML file designates that some components
are to be installed from CD-ROM.
SETUP_DISTRO : If an OS distribution was detected, this is its
name.
SETUP_OPTIONTAGS : A blank-separated list of the option tags for the
<option>'s selected for installation.
SETUP_ARCH : Architecture of the installer binary. It might be
different than the kernel's architecture. (ex:
64 bit kernel and 32 bit userspace on an x86_64
machine)
About localization :
The 'lang' values are matched against the value of the LANG environment
variable. The special value 'none' is matched only when there is no LANG
environment variable set (the default locale).
!!! FIXME: the next paragraph isn't true at this moment !!!
A locale is matched if the specified value is found at the beginning of
LANG. For example, "fr" will match both the "fr" and "fr_CA" values. In
order for the more specialized locale values to be matched correctly,
the shorter values should be be specified last (i.e. if you have different
translations, list "fr" after "fr_CA" in the XML file).
!!! FIXME: the previous paragraph isn't true at this moment !!!
About distributions :
It is now possible to have options or components specific to a specific brand
of the operating system (i.e. the Linux distribution). Specifications have
the form:
[!]distribution-major.minor-policy
'major' and 'minor' are both optional and describe the minimal release numbers
for the detected distribution. If specified, versions at least this recent
will match.
'policy' is also an optional string that describes the matching policy for this
version, i.e. if you don't necesarily want to match all later releases of a
distribution. Possible values are 'up' (the default), 'major' (includes all
versions of the same major number), and 'exact' (for the exact specification).
The optional leading ! character is used to negate the result of the matching.
For example, to match all non-Linux systems, use "!linux".
Currently, the recognized distribution names are :
Linux: redhat, mandrake, suse, debian, slackware, caldera, linuxppc, yellowdog,
turbo, linux, gentoo
UNIX: freebsd, solaris, hpux, irix, sco, aix
'linux' is a special distribution name that can be used to differentiate between a GNU/Linux
system and other UNIX flavors. The 'linux' version numbers correspond to the kernel version.
Hence, the 'linux' name matches all distributions.
Examples: redhat-7.1 (will match RedHat 7.1 and up)
mandrake (will match all versions of Mandrake Linux)
slackware-7 (will match Slackware 7.0 and up)
slackware-7.0-major (will match all Slackware 7.x releases, but not 8.x and up)
caldera-3.1-exact (will match Caldera OpenLinux 3.1 only)
linux-2.4 (requires a 2.4.x Linux kernel or above)
About Boolean Expressions :
Many elements support the 'if' or 'condition' attribute to reference complex expressions
using the Setup boolean variables. The expressions have to follow the following syntax:
expression := [!]<operator>(<expression1>,<expression2>) |
[!]<boolean name>
Supported operators are : + (logical "and"), | (logical "or"), and ^ (logical "exclusive or").
Any expression can be negated by a ! prefix.
An undefined boolean is the same as a false boolean.
Some examples :
Match Fedora on PowerPC system:
+(fedora,ppc)
Match one of SuSE, Redhat 9 or Fedora, on all but Intel:
+(^(suse,+(redhat,distro-major-9),fedora),!x86)
About Meta-Installations :
Loki Setup allows you to install several products from the same interface.
This is achieved by defining a top-level "meta-installation" XML file, that
will contain a list of products in the "option" elements. The user will then
be prompted to choose one of the products, and setup will restart itself
with the actual XML file corresponding to the product.
Here are the rules to write a meta-installation XML file :
- Specify the "meta" attribute in the top-level install attribute (value must
be "yes").
- Do not specify any files for each option. All of the options must have the
"product" attribute set to the name of the XML file for the particular product.
Note that the file name must be given relative to setup's startup directory, so
don't forget to prepend "setup.data" if appropriate.
- One of the options should have the "install=true" attribute, to specify a default
selection.
- README and EULA files can be specified, but won't be installed.
Here is a sample XML meta-installation specification :
<?xml version="1.0" standalone="yes"?>
<install product="Meta Install" desc="Loki Demo Disc" version="1.0" meta="yes">
<readme>README</readme>
<option product="setup.data/civ.xml" install="true">
Civ: CTP
</option>
<option product="setup.data/heroes3.xml">
Heroes3
</option>
<option product="setup.data/myth2.xml">
Myth II
</option>
</install>
-------------------------------------------------------------------------
Example XML product specification:
(Note: There can be no comments within the file itself, so we will denote
comments using '# ..." notation)
<?xml version="1.0" standalone="yes"?>
<install product="foo" desc="An example product" version="1.0"
path="/opt"
preinstall="sh setup.data/foo-preinst.sh $*"
postinstall="sh setup.data/foo-postinst.sh $*"
url="http://www.products.kom/foo/index.html"
>
<eula>license.txt</eula>
<eula lang="fr">license-fr.txt</eula>
<readme>README</readme>
# This installs a product named "foo" in /opt/foo by default.
# The user may specify a different installation directory.
# The installer will prompt the user with the license contained in the
# file "license.txt", and will execute foo-preinst.sh and foo-postinst.sh
# before and after installing the product. When the product is finished
# installing, a browser will be launched to the site:
# http://www.products.kom/foo/index.html
<option install="true">
Base Install # Option called "Base Install" contains a binary,
# some data files, and two optional editors.
<help>Required for use</help>
<help lang="fr">Requis pour utilisation</help>
<binary arch="any" libc="any" symlink="foo" icon="icon.xpm">
foo
</binary>
<files lang="fr">
README.fr
<files>
<files>
icon.xpm
edit.xpm
data/*.dat
</files>
<option>
Curses Editor
<help>Terminal editor for foo data files</help>
<binary arch="any" libc="any">
foo-edit.ncurses
</binary>
</option>
<option>
Motif Editor
<help>X windows editor for foo data files</help>
<binary arch="any" libc="any">
foo-edit.motif
</binary>
</option>
<script>
# A script to finish the editor installation
# It would set the default editor and edit desktop menu items
# The first parameter to the script is the install path
sh setup.data/edit-postinst.sh $*
</script>
</option>
<option size="12M">
Extra Data # Option called "Extra Data" contains extra files
<files>
extra/*.dat
</files>
</option>
</install>
-------------------------------------------------------------------------