Let's look at a minimal example of package.xml file:
<package type="addon" name="nuxeo-automation" version="5.3.2"> <title>Nuxeo Automation</title> <description>A service that enables building complex business logic on top of Nuxeo services using scriptable operation chains</description> <platforms> <platform>cap-8.3</platform> <platform>server-8.4*</platform> </platforms> </package>
This is a minimal package manifest. It is defining a package nuxeo-automation at version 5.3.2 and of type addon. The package can be installed on platforms dm-5.3.2 and dam-5.3.2.
TODO: replace fixed versions in platforms with range of versions.
Also, the package title and description that should be used by the UI are specified by the
Note that the package names used in these examples are fictional.
Let's look at the full version of the same package manifest:
<package type="addon" name="nuxeo-automation" version="5.3.2"> <title>Nuxeo Automation</title> <description>A service that enables building complex business logic on top of Nuxeo services using scriptable operation chains</description> <classifier>Open Source</classifier> <home-page>http://some.host.com/mypage</home-page> <vendor>Your Company</vendor> <installer class="org.nuxeo.connect.update.impl.task.InstallTask" restart="false"/> <uninstaller class="org.nuxeo.connect.update.impl.task.UninstallTask" restart="false"/> <validator class="org.nuxeo.MyValidator"/> <platforms> <platform>cap-8.3</platform> <platform>server-8.4*</platform> </platforms> <dependencies> <package>nuxeo-core:8.3.1:8.3.2</package> <package>nuxeo-runtime:8.3.1</package> </dependencies> <optional-dependencies> <package>nuxeo-web-ui:1.0.0:1.0.2</package> <package>nuxeo-jsf-ui:1.0.0</package> </optional-dependencies> <supported>false</supported> <hotreload-support>true</hotreload-support> <require-terms-and-conditions-acceptance>false</require-terms-and-conditions-acceptance> <nuxeo-validation>primary_validation</nuxeo-validation> <production-state>production_ready</production-state> <license>LGPL</license> <license-url>http://www.gnu.org/licenses/lgpl.html</license-url> <visibility>PUBLIC</visibility> </package>
You can see the usage of
uninstaller elements. These are used to specify the task implementation to be used when installing and uninstalling.
addon. The installation behavior may vary depending on the package type. For instance, the
mp-hotfixcommand looks for
hotfixpackages and the
studiopackages have a special treatment in the Administration page and some specific packages dependency resolution rules. See org.nuxeo.connect.update.PackageType.
package name: Open field. The name is used to reference the package in
nuxeoctl, in the Administration page and on http://marketplace.nuxeo.com/, so it is recommended to use a lowercase dash-separated name.
package version: Versions are in the form
major.minor.patch-classifierwith some "special" classifiers like "beta", "SNAPSHOT"... See org.nuxeo.connect.update.Version.
title: Open field.
description: HTML field.
home-page: The URL where more information can be found about this package.
vendor: The vendor represent the entity providing and maintaining the package.
uninstaller: See org.nuxeo.connect.update.model.TaskDefinition.
validator: See org.nuxeo.connect.update.Validator.
supported: True or False. Is the package maintenance guaranteed by a support contract with the vendor.
hotreload-support: True or False. Can the package be "hot reloaded" (cf Nuxeo Studio, Dev mode...).
require-terms-and-conditions-acceptance: True or False. Determines if the package install requires terms and conditions acceptance by the administrator.
nuxeo-validation: A validation status:
nuxeo_certified. See org.nuxeo.connect.update.NuxeoValidationState.
production-state: A production status:
production_ready. See org.nuxeo.connect.update.ProductionState.
license: Open field: GPL, BSD, LGPL...
license-url: If no URL is provided, then a
license.txtfile should be included in the package.
PRIVATE(restricted to specific users and/or projects),
MARKETPLACE(restricted to registered users),
DEV(restricted to registered users) or
PUBLIC(no restriction). The visibility determines the channel where the package will be distributed and how it can be installed. See org.nuxeo.connect.update.PackageVisibility.
platforms: The list of platforms supported by this package.
dependencies: The list of package dependencies. See org.nuxeo.connect.update.PackageDependency.
optional-dependencies: The list of package optional dependencies. Used for packages which use the conditional bundle installation.
conflicts: The list of packages conflicting with the current package.
provides: The list of packages useless if the current package is installed.
Versions are in the form
major.minor.patch-classifier with some "special" classifiers like "beta", "SNAPSHOT"...
SNAPSHOT packages are overwritten without confirmation.
Release packages cannot be overwritten. They must be deleted before re-deploy (although not recommended).
Versioning policy is free while it follows the pattern
major.minor.patch-classifier described in org.nuxeo.connect.update.Version.
The Nuxeo policy is:
- major: increased on major changes (features, API...)
- minor: increased between Platform generations (7.x, 8.x...)
- patch: increased per release
For instance, Nuxeo would use:
1.0.0for the first package release targeting Nuxeo
1.0.2... for the next packages targeting
1.1.0for the first package release targeting Nuxeo
1.1.2... for the next packages targeting
1.2.0for the first package release targeting Nuxeo
- And in case of important code changes, respectively
2.2.0for the next packages targeting
Maintenance branches are usually named
major.minor_LTS: for instance,
Package dependencies, optional-dependencies, conflicts and provides are in the form
A package can be empty with only package dependencies in its manifest. Such a package is called a meta-package.
Meta-packages are a good solution to manage relations between packages and to ease deployment.
If a meta-package purpose is to define a unique configuration with a reproducible install, then you should configure its dependencies with equal min and max versions.
The dependency resolution system automatically manages the target platform constraint and looks for the solution providing the more recent packages. Thus, it is usually not necessary to specify a min or max version for the dependencies.
If you really need to specify a min version, then it is usually wrong to also specify a max version unless you work on a meta-package.
It is not necessary to make a package depend on a hotfix to benefit from that hotfix. The hotfix bundles are deployed indifferently from the order of install between a hotfix package and an addon package. In other words, bugs are being fixed by hotfix packages. It is normal that an installed package have some bugs if the relevant hotfix package is not installed. It's not the purpose of a package to embed its fixes.
A hotfix is not compliant with anything but a stock release distribution. It is not compliant with a SNAPSHOT distribution (built from the maintenance branch), nor with a hotfix distribution (built from a hotfix release). improvement will make the maintenance distribution (SNAPSHOT or release) "provide" the corresponding hotfix packages. It won't apply on public packages. It won't be backported.
If a package depends on an hotfix:
- It must not be PUBLIC since hotfix are only available to registered users.
- It won't be installable on SNAPSHOT and hotfix distributions.
- It should be a release package since SNAPSHOT packages cannot be properly tested if they depend on a hotfix.
If you really want to make a package depending on a hotfix package:
- Think about only stating that dependency in the package description, else
- Check that the package is not PUBLIC
- Do it only for the release and remove the dependency for the next SNAPSHOT.
Some packages may use the conditional bundle install in their install.xml (TODO: add link to conditional bundle installation documentation https://jira.nuxeo.com/browse/NXP-19789). When a package is being installed together with one of the packages referenced in his install.xml, those must be installed in the right order to avoid incomplete installation. Similarly, if a package is installed before one of the packages referenced in his install.xml, it must be reinstalled when one of the referenced package is installed.
This is the purpose of the optional dependencies. An optional dependency will never be required, but will always be installed before its dependant package.
In the above example, if you try to install
nuxeo-automation along with
nuxeo-jsf-ui will be installed first. If you install
nuxeo-automation alone first, then you install
nuxeo-automation will be reinstalled when you install
In any case, you still can have
nuxeo-automation installed without having