XML Package Definition Files (version 1.0)

VALET packages (and their versions) are defined in XML files; each package available on a system has its own package definition file, named as «package-id».vpkg. For example, all versions of Mathematica would be defined in a file named mathematica.vpkg.

Package definition files are collocated in a directory. By default (and minimally), the etc subdirectory inside the valet installation directory is used.

A VALET package definition is expressed in XML. The XML schema that explicitly declares the XML language can be found here.

The XML document element is named package and has a single required attribute:

<package id="mathematica">
  <description>Wolfram Mathematica</description>
  <url>http://www.wolfram.com/</url>
  <prefix>/opt/mathematica</prefix>
    :
</package>

The id must match that of the package definition filename. A package can optionally have a human-readable description and a reference URL (e.g. the vendor/product web site).

Ideally, all versions of a package are installed in unique directories under a common parent directory. If this is indeed the case, then a prefix element can be added to the package element as shown above. When the individual package versions are later defined, they can provide a relative path in their own prefix element which VALET takes as being relative to the package's prefix path.

Each version of a package is defined as a version XML element with a required id attribute:

    :
  <version id="6">
    <description>Wolfram Mathematica version 6</description>
    <url>http://www.wolfram.com/6</url>
    <prefix>6.0.1</prefix>
    <bindir>Executables</bindir>
    <dependencies>
      <package id="pgi/10"/>
    </dependencies>
    <incompatibilities>
      <package id="matlab/*"/>
    </incompatibilities>
      :
  </version>
    :

The optional description and url elements override the value presented in the parent package element.

As mentioned earlier, the prefix element specified here is a relative path that VALET assumes is relative to the prefix provided by the parent package: /opt/mathematica/6.0.1 would be the full path in this case.

Zero or more bindir elements specify paths that should be added to the PATH environment variable. Relative paths are taken to be relative to the prefix directory. The directories that can be specified are:

If any of these elements is not present for a version, then VALET automatically considers the default directory(s). In all cases, only directories that actually exist will be setup in the environment.

For software packages that are built using other packages managed by VALET, a list of dependencies can be specified. Each dependency is expressed as an empty package element with the id of the other (versioned) package; in the example above, Mathematica 6 for some reason depends on version 6 of the Portland compiler suite. When configuring the environment, VALET will automatically attempt to include all dependency packages' configuration details, as well.

A list of incompatibilities can be included to express that a versioned package conflicts with some other versioned package. Each incompatibility is expressed as an empty package element with the id of the other (versioned) package. Note in the example above Mathematica 6 conflicts (somehow) with any version of Matlab: the * acts as a wildcard¹⁾. Inclusion of any version of Matlab either prior to or after this versioned package's inclusion will yield an error. Of course, actual version ids can be present, and as always the lack of a version id implies the default version of the package.

Both the dependencies and incompatibilities elements can also contain environment variable tests. The predicate element is used to model such tests and is described later in this document.

Multiple version elements may appear in a package document; all version elements are children of the package element. A default-version element in the package document indicates which version should be considered the default; omitting the default-version element, the first version element will be the default for the package:

<package id="mathematica">
    :
  <default-version>7</default-version>
  <version id="6">..</version>
  <version id="7">..</version>
  <version id="8">..</version>
    :
</package>

A version alias is a unique package version that points to a sibling version. For example, Gaussian releases their G09 product and its incremental updates as a series, e.g. g09a01, g09a02, g09b03, etc. Most users probably don't care what revision of G09 they are using, so long as they are using G09. By specifying a version alias

    :
  <version id="g09" alias-to="g09b03"/>
    :

users can always just request gaussian/g09 and the system administrator can change the alias target as future incremental updates are installed on the system. As illustrated, a version alias starts like a regular version element but has no content and includes the additional attribute alias-to. The alias must have its own unique version identifier in the id attribute, and the identifier of some other version in the alias-to attribute.

In some cases there may be additional environment variables that need to be modified for a package/version. To facilitate this, zero or more export elements can be added to a package or version element:

<package id="mathematica">
    :
  <export variable="MATHEMATICA_IN_USE">1</export>
  <version id="8">
      :
    <export variable="MATHEMATICA_DOCS" action="path-append">${HOME}/mma_8</export>
      :
  </version>
    :
</package>

An export element inside a version element that has the same variable name as one in the parent package overrides the behavior defined in the package. The action can be:

If no action attribute is specified the set action is assumed.

If there is additional "work" that cannot be encapsulated in VALET configuration directives, the system administrator can write an external script that will be sourced into the user's shell. A version element can have zero or more script elements within it that provide the path to each such script:

    :
  <version id="6">
      :
    <script shell="sh">/opt/mathematica/bin/remote_kernel.sh</script>
      :
  </version>
    :

VALET defines some environment variables that scripts may want to use:

Scripts are invoked at the end of the environment configuration process, so all VALET-oriented changes to the environment are in-place when scripts are executed.

In some cases it may be necessary to test the value of one or more environment variables to determine whether or not the package setup should succeed or fail. For example, if the user has no GAUSS_SCRDIR defined then Gaussian will have no directory in which to write scratch files. This could be described as either a dependency or an incompatibility.

Such tests are modeled with a predicate element. A predicate element is valid inside the dependencies and incompatibilities elements of a version element. The predicate element requires a variable attribute; an operator and stage attribute may also be specified:

     :
    <dependencies>
       :
      <predicate variable="GAUSS_SCRDIR" operator="is-set" stage="post-condition"/>
       :
    </dependencies>
     :

In this case, the predicate could also be configured as an incompatibility:

     :
    <incompatibilities>
       :
      <predicate variable="GAUSS_SCRDIR" operator="not-is-set" stage="post-condition"/>
       :
    </incompatibilities>
     :

The stage attribute dictates whether the test should be performed before (pre-condition) or after (post-condition) VALET makes changes to the environment. If no stage attribute is specified, the predicate will be a pre-condition.

Valid operators are:

For binary operators, the required argument is provided in a <value> element inside the <predicate> element. For example, to ensure that setup does not proceed if a user has pre-set GAUSS_SCRDIR to a filesystem that should not be used as scratch, the following incompatibility predicate might be used:

     :
    <incompatibilities>
       :
      <predicate variable="GAUSS_SCRDIR" operator="matches">
        <value>^/(home|archive)/</value>
        <explanation>Storing Gaussian scratch files on /home or /archive is forbidden.</explanation>
      </predicate>
       :
    </incompatibilities>
     :

If a user subsequently attempts to vpkg_require gaussian the explanation will be displayed if they have GAUSS_SCRDIR misconfigured:

ERROR: an error occurred while altering your environment
REASON: Storing Gaussian scratch files on /home or /archive is forbidden.

All predicates must pass in order for environment configuration to succeed; essentially, success is the logical AND of all predicates specified.

Prev: Packages | Next: XML Package Files, version 2