Package Repository

expath-pkg.xml

As an example, the EXPath descriptor for the documentation app is shown below:

<package xmlns="http://expath.org/ns/pkg" abbrev="exist-documentation" name="http://exist-db.org/apps/doc" spec="1.0" version="5.2.1-SNAPSHOT">
  <title>
    eXist-db Documentation
  </title>
  <home>
    https://www.github.com/exist-db/documentation
  </home>
  <dependency processor="http://exist-db.org" semver-min="5.3.0-SNAPSHOT"/>
  <dependency package="http://exist-db.org/html-templating"/>
</package>

The schema of this file is documented in the specification. In short, the attributes are as follows:

name

URI used as a unique identifier for the package. The URI does not need to point to an existing web site. The package repository will use this URI to identify a package within the system.

abbrev

Short abbreviation for the package. This will be used as part of the file name for the .xar. We recommend to choose a short, simple name, without spaces or punctuation characters.

version

Version of the package. This allows the Package Manager to determine if newer versions of the same package are available.

spec

Version of the packaging specification the package conforms to. Always 1.0 for the current specification.

<title>

Descriptive title to display to the user (in the Dashboard)

<dependency package="http://exist-db.org/html-templating"/>

<dependency processor="eXist-db" semver-min="3.1.0" semver-max="4.5.0"/>

<package xmlns="http://expath.org/ns/pkg" name="http://www.functx.com" abbrev="functx" version="1.0" spec="1.0">
  <title>
    FunctX library
  </title>
  <xquery>
    <namespace>
      http://www.functx.com
    </namespace>
    <file>
      functx.xql
    </file>
  </xquery>
</package>

/expath-pkg.xml
/repo.xml
/content/functx.xql

import module namespace functx="http://www.functx.com";

functx:capitalize-first('hello')

<package xmlns="http://exist-db.org/ns/expath-pkg">
  <jar>
    expath-crypto.jar
  </jar>
  <java>
    <namespace>
      http://expath.org/ns/crypto
    </namespace>
    <class>
      org.expath.exist.crypto.ExistExpathCryptoModule
    </class>
  </java>
</package>

repo.xml

The deployment descriptor contains additional metadata and defines how the package will be installed into an eXist-db database instance. For example:

<meta xmlns="http://exist-db.org/xquery/repo">
  <description>
    eXist-db Documentation
  </description>
  <author>
    eXist-db
  </author>
  <website>
    https://www.github.com/exist-db/documentation
  </website>
  <status>
    stable
  </status>
  <license>
    GNU Lesser General Public License, version 2.1
  </license>
  <copyright>
    true
  </copyright>
  <type>
    application
  </type>
  <target>
    doc
  </target>
  <prepare>
    pre-install.xql
  </prepare>
  <deployed/>
</meta>

The two settings: type and target determine how a package is handled by the installer:

An application package has <type> set to application and specifies a <target> because it needs to be deployed into the database. Contrary to this, a library package only registers XQuery or other modules, but no resources need to be stored into the database, so <target> is empty.

<type>

Should be set to either application or library. We assume a library has no GUI. A library will therefore not be shown on the main Dashboard page, which only lists applications.

<target>

Specifies the collection where the contents of the package will be stored. Top-level files in the package will end up in this collection, resources in sub-directories will go into sub-collections. Please note that the target collection can be changed by the package manager during install: It is a recommendation, not a requirement.

The collection path should be relative to the repository root collection defined in the configuration (usually /db/apps).

<permissions>

You can define package specific permissions in the repo.xml to use when uploading package contents like this:

<permissions user="app-user" password="123" group="app-group" mode="rw-rw-r--"/>

All resources and collections will be owned by the specified user and permissions will be changed to those given in mode. If the user does not exist, the deploy function will try to create it, using the password specified in the password attribute.

Concerning permissions: the execute x flag will be set automatically on all XQuery files, in addition to the default permissions defined in the descriptor. For more control over permissions, use a post-install XQuery script (see element <finish> below).

It is generally recommended to specify users in this manner when a package requires write privileges to the database, and to use a custom user-group (i.e. not dba). To avoid conflicts with locally defined user-names and group names, packages that do not require write access can omit permissions in their repo.xml. These packages will be assigned to the guest user group by default.

<prepare>

Points to an XQuery script inside the root of the package archive, which will be executed before any package data is uploaded to the database. By convention the XQuery script is called pre-install.xql, but this is not a requirement.

If you create a package via eXide, it will generate a default pre-install.xql which uploads the default collection configuration to the system collection. This needs to be done before deployment to guarantee that index definitions are applied when data is uploaded to the db.

The target collection, the file system path to the current package directory and eXist-db's home directory, are passed to the script as external variables:

(: file path pointing to the eXist-db installation directory :)
declare variable $home external;
(: path to the directory containing the unpacked .xar package :)
declare variable $dir external;
(: the target collection into which the app is deployed :)
declare variable $target external;

The script can use these to read files contained in the package.

<finish>

Like <prepare>, this element must point to an XQuery script. This will be executed after all data has been uploaded to the database. It receives the same external variables as the prepare script. The convention is to name the script post-install.xql.

Use the <finish> script to run additional tasks or move data into different collections. For example, the XQuery function documentation app runs an indexing task from the finish trigger to extract documentation from all XQuery modules known to the database at the time.

<deployed>

This element is set automatically when the package is deployed into a database instance. It is used by eXide to track changes and does not need to be specified in the original repo.xml descriptor.