docs/package/package-xml.md

   1 # package.xml
   2
   3 The `package.xml` is the core component of every package.
   4 It provides the meta data (e.g. package name, description, author) and the instruction set for a new installation and/or updating from a previous version.
   5
   6 ## Example
   7
   8 {jinja{ codebox(
   9   title="package.xml",
  10   language="xml",
  11   filepath="package/package.xml"
  12 ) }}
  13
  14
  15 ## Elements
  16
  17 ### `<package>`
  18
  19 The root node of every `package.xml` it contains the reference to the namespace and the location of the XML Schema Definition (XSD).
  20
  21 The attribute `name` is the most important part, it holds the unique package identifier and is mandatory.
  22 It is based upon your domain name and the package name of your choice.
  23
  24 For example WoltLab Suite Forum (formerly know an WoltLab Burning Board and usually abbreviated as `wbb`) is created by WoltLab which owns the domain `woltlab.com`.
  25 The resulting package identifier is `com.woltlab.wbb` (`<tld>.<domain>.<packageName>`).
  26
  27 ### `<packageinformation>`
  28
  29 Holds the entire meta data of the package.
  30
  31 #### `<packagename>`
  32
  33 This is the actual package name displayed to the end user, this can be anything you want, try to keep it short.
  34 It supports the attribute `languagecode` which allows you to provide the package name in different languages, please be aware that if it is not present, `en` (English) is assumed:
  35
  36 ```xml
  37 <packageinformation>
  38         <packagename>Simple Package</packagename>
  39         <packagename languagecode="de">Einfaches Paket</packagename>
  40 </packageinformation>
  41 ```
  42
  43 #### `<packagedescription>`
  44
  45 Brief summary of the package, use it to explain what it does since the package name might not always be clear enough.
  46 The attribute `languagecode` is available here too, please reference to [`<packagename>`](#packageName) for details.
  47
  48 #### `<version>`
  49
  50 The package's version number, this is a string consisting of three numbers separated with a dot and optionally followed by a keyword (must be followed with another number).
  51
  52 The possible keywords are:
  53
  54 - Alpha/dev (both is regarded to be the same)
  55 - Beta
  56 - RC (release candidate)
  57 - pl (patch level)
  58
  59 Valid examples:
  60
  61 - 1.0.0
  62 - 1.12.13 Alpha 19
  63 - 7.0.0 pl 3
  64
  65 Invalid examples:
  66
  67 - 1.0.0 Beta (keyword Beta must be followed by a number)
  68 - 2.0 RC 3 (version number must consists of 3 blocks of numbers)
  69 - 1.2.3 dev 4.5 (4.5 is not an integer, 4 or 5 would be valid but not the fraction)
  70
  71 #### `<date>`
  72
  73 Must be a valid [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) date, e.g. `2013-12-27`.
  74
  75 ### `<authorinformation>`
  76
  77 Holds meta data regarding the package's author.
  78
  79 #### `<author>`
  80
  81 Can be anything you want.
  82
  83 #### `<authorurl>`
  84
  85 > (optional)
  86
  87 URL to the author's website.
  88
  89 ### `<requiredpackages>`
  90
  91 A list of packages including their version required for this package to work.
  92
  93 #### `<requiredpackage>`
  94
  95 Example:
  96
  97 ```xml
  98 <requiredpackage minversion="2.0.0" file="requirements/com.woltlab.wcf.tar">com.woltlab.wcf</requiredpackage>
  99 ```
 100
 101 The attribute `minversion` must be a valid version number as described in [`<version>`](#version).
 102 The `file` attribute is optional and specifies the location of the required package's archive relative to the `package.xml`.
 103
 104 ### `<optionalpackage>`
 105
 106 A list of optional packages which can be selected by the user at the very end of the installation process.
 107
 108 #### `<optionalpackage>`
 109
 110 Example:
 111
 112 ```xml
 113 <optionalpackage file="optionals/com.woltlab.wcf.moderatedUserGroup.tar">com.woltlab.wcf.moderatedUserGroup</optionalpackage>
 114 ```
 115
 116 The `file` attribute specifies the location of the optional package's archive relative to the `package.xml`.
 117
 118 ### `<excludedpackages>`
 119
 120 List of packages which conflict with this package. It is not possible to install it if any of the specified packages is installed. In return you cannot install an excluded package if this package is installed.
 121
 122 #### `<excludedpackage>`
 123
 124 Example:
 125
 126 ```xml
 127 <excludedpackage version="3.1.0 Alpha 1">com.woltlab.wcf</excludedpackage>
 128 ```
 129
 130 The attribute `version` must be a valid version number as described in the [\<version\>](#version) section. In the example above it will be impossible to install this package in WoltLab Suite Core 3.1.0 Alpha 1 or higher.
 131
 132 ### `<compatibility>`
 133 !!! info "Available since WoltLab Suite 3.1"
 134 !!! warning "With the release of WoltLab Suite 5.2 the API versions were abolished. Instead of using API versions packages should exclude version `6.0.0 Alpha 1` of `com.woltlab.wcf` going forward."
 135
 136 WoltLab Suite 3.1 introduced a new versioning system that focused around the API compatibility and is intended to replace the `<excludedpackage>` instruction for the Core for most plugins.
 137
 138 The `<compatibility>`-tag holds a list of compatible API versions, and while only a single version is available at the time of writing, future versions will add more versions with backwards-compatibility in mind.
 139
 140 Example:
 141
 142 ```xml
 143 <compatibility>
 144         <api version="2018" />
 145 </compatibility>
 146 ```
 147
 148 #### Existing API versions
 149
 150 | WoltLab Suite Core | API-Version | Backwards-Compatible to API-Version |
 151 |---|---|---|
 152 | 3.1 | 2018 | n/a |
 153
 154 ### `<instructions>`
 155
 156 List of instructions to be executed upon install or update. The order is important, the topmost `<instruction>` will be executed first.
 157
 158 #### `<instructions type="install">`
 159
 160 List of instructions for a new installation of this package.
 161
 162 #### `<instructions type="update" fromversion="…">`
 163
 164 The attribute `fromversion` must be a valid version number as described in the [\<version\>](#version) section and specifies a possible update from that very version to the package's version.
 165
 166 !!! warning "The installation process will pick exactly one update instruction, ignoring everything else. Please read the explanation below!"
 167
 168 Example:
 169
 170 - Installed version: `1.0.0`
 171 - Package version: `1.0.2`
 172
 173 ```xml
 174 <instructions type="update" fromversion="1.0.0">
 175         <!-- … -->
 176 </instructions>
 177 <instructions type="update" fromversion="1.0.1">
 178         <!-- … -->
 179 </instructions>
 180 ```
 181
 182 In this example WoltLab Suite Core will pick the first update block since it allows an update from `1.0.0 -> 1.0.2`.
 183 The other block is not considered, since the currently installed version is `1.0.0`. After applying the update block (`fromversion="1.0.0"`), the version now reads `1.0.2`.
 184
 185 #### `<instruction>`
 186
 187 Example:
 188
 189 ```xml
 190 <instruction type="objectTypeDefinition">objectTypeDefinition.xml</instruction>
 191 ```
 192
 193 The attribute `type` specifies the instruction type which is used to determine the package installation plugin (PIP) invoked to handle its value.
 194 The value must be a valid file relative to the location of `package.xml`.
 195 Many PIPs provide default file names which are used if no value is given:
 196
 197 ```xml
 198 <instruction type="objectTypeDefinition" />
 199 ```
 200
 201 There is a [list of all default PIPs](pip.md) available.
 202
 203 !!! warning "Both the `type`-attribute and the element value are case-sensitive. Windows does not care if the file is called `objecttypedefinition.xml` but was referenced as `objectTypeDefinition.xml`, but both Linux and Mac systems will be unable to find the file."
 204
 205 In addition to the `type` attribute, an optional `run` attribute (with `standalone` as the only valid value) is supported which forces the installation to execute this PIP in an isolated request, allowing a single, resource-heavy PIP to execute without encountering restrictions such as PHP’s `memory_limit` or `max_execution_time`:
 206
 207 ```xml
 208 <instruction type="file" run="standalone" />
 209 ```
 210
 211 #### `<void/>`
 212
 213 Sometimes a package update should only adjust the metadata of the package, for example, an optional package was added.
 214 However, WoltLab Suite Core requires that the list of `<instructions>` is non-empty.
 215 Instead of using a dummy `<instruction>` that idempotently updates some PIP, the `<void/>` tag can be used for this use-case.
 216
 217 Using the `<void/>` tag is only valid for `<instructions type="update">` and must not be accompanied by other `<instruction>` tags.
 218
 219 Example:
 220
 221 ```xml
 222 <instructions type="update" fromversion="1.0.0">
 223         <void/>
 224 </instructions>
 225 ```