diff --git a/src/main/xar-resources/data/repo/repo.xml b/src/main/xar-resources/data/repo/repo.xml index c45c6966..777d865d 100644 --- a/src/main/xar-resources/data/repo/repo.xml +++ b/src/main/xar-resources/data/repo/repo.xml @@ -24,8 +24,8 @@ Introduction The package repository is based on and extends the EXPath Packaging System. The core of - the EXPath packaging specification has been designed to work across different XQuery + xlink:href="http://expath.org/modules/pkg/">EXPath Packaging System. The core + of the EXPath packaging specification has been designed to work across different XQuery implementations and is targeted at managing extension libraries (including XQuery, Java or XSLT code modules). eXist-db extends this core by adding a facility for the automatic deployment of entire applications into the database. @@ -73,16 +73,20 @@ directory: expath-pkg.xml and repo.xml: - expath-pkg.xml + + expath-pkg.xml + This is the standard EXPath descriptor as defined by the EXPath specification. It specifies the unique name of the package, lists dependencies and any library modules to register globally. See . + linkend="sect-expathpkg"/>. - repo.xml + + repo.xml + The eXist-db specific deployment descriptor: it contains additional metadata about the package and controls how it will be deployed into the @@ -92,6 +96,10 @@ For library packages repo.xml is optional. However, we recommend to always provide it for better tool integration. + The following is not mentioned in the EXPath spec, but if an image resource with the + filename icon.png or icon.svg is found in the root + directory of an app, the eXist-db dashboard will display that user-supplied image + instead of the default eXist-db blue dotted X. @@ -154,8 +162,8 @@ expath-pkg.xml descriptor. For eaxample: It is also possible to create a dependency on a specific version, based on - Semantic - Versioning. This can be done by adding either of the attributes: + Semantic + Versioning. This can be done by adding either of the attributes: version, semver, semver-min, semver-max: @@ -189,8 +197,8 @@ semver-max - Defines a maximum version according to the - semver scheme. + Defines a maximum version according to the semver + scheme. @@ -216,7 +224,7 @@ and may be used by other packages without knowing where the module code is stored. For example, the following descriptor registers the module - functx.xql using the given namespace: + functx.xql using the given namespace: The namespace has to correspond to the namespace defined in the module declaration of the XQuery module. The file should be placed into a subdirectory @@ -282,26 +290,50 @@ - Type of package - type - target + + Type of package + + + type + + + target + - Application package - application - specified + + Application package + + + application + + + specified + - Resource package - library - specified + + Resource package + + + library + + + specified + - Library package - library - not specified + + Library package + + + library + + + not specified + @@ -338,8 +370,8 @@ permissions You can define package specific permissions in the - repo.xml to use when uploading package contents like - this: + repo.xml to use when uploading package contents + like this: All resources and collections will be owned by the specified user and permissions will be changed to those given in mode. @@ -350,7 +382,7 @@ 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). + 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 @@ -366,13 +398,13 @@ 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 + 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. + 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: @@ -388,7 +420,7 @@ 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. + 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 @@ -434,14 +466,14 @@ Configuring the repository root The root collection for deployed packages can be configured in - conf.xml: + conf.xml: The install location specified in the target element of - repo.xml will always be relative to this root collection. + repo.xml will always be relative to this root collection. eXist-db's URL rewriting is by default configured to map any path starting with /apps to the repository root collection. Check - etc/webapp/WEB-INF/controller-config.xml and the URL rewriting documentation. + etc/webapp/WEB-INF/controller-config.xml and the URL rewriting documentation. @@ -453,10 +485,10 @@ programmatically install, remove or inspect packages. The Dashboard Package Manager relies on the same functions. The module distinguishes between installation and - deployment steps. The reason for this distinction is: while the + deployment steps. The reason for this distinction is: while the installation process is standardized by the EXPath packaging specification, the deployment step is implementation defined and specific to eXist-db. - Installation will register a package with the EXPath packaging + Installation will register a package with the EXPath packaging system, but not copy anything into the database. Deployment will deploy the application into the database as specified by the repo.xml descriptor. @@ -489,14 +521,14 @@ distribute applications to your customers. The eXist-db repository is implemented by the application package http://exist-db.org/apps/public-repo. The code can be downloaded from the eXist-db GitHub + xlink:href="https://github.com/eXist-db/public-xar-repo">eXist-db GitHub repo. Once you have built and installed the app, you can upload the package .xar files you wish to distribute into the collection - public-repo/public. To make the uploaded .xar files + public-repo/public. To make the uploaded .xar files available, run the query public-repo/modules/update.xql once as an admin user. This will create a document apps.xml in - public-repo/public. + public-repo/public.