5.3/package_package-xml.html

   1 <!DOCTYPE html>
   2 <head>
   3     <meta charset="utf-8">
   4 <meta http-equiv="X-UA-Compatible" content="IE=edge">
   5 <meta name="viewport" content="width=device-width, initial-scale=1">
   6 <meta name="description" content="">
   7 <meta name="keywords" content=" ">
   8 <title>package.xml | WoltLab Suite 5.3 Documentation</title>
   9
  10 <link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/syntax.css">
  11 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,300,600">
  12 <link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/font-awesome.min.css">
  13 <!--<link rel="stylesheet" type="text/css" href="css/bootstrap.min.css">-->
  14 <link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/modern-business.css">
  15 <link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/lavish-bootstrap.css">
  16 <link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/customstyles.css">
  17 <link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/theme-blue.css?v=3">
  18
  19 <script src="https://docs.woltlab.com/5.3/js/jquery.min.js"></script>
  20 <script src="https://docs.woltlab.com/5.3/js/jquery.cookie.min.js"></script>
  21 <script src="https://docs.woltlab.com/5.3/js/jquery.navgoco.min.js"></script>
  22 <script src="https://docs.woltlab.com/5.3/js/bootstrap.min.js"></script>
  23 <script src="https://docs.woltlab.com/5.3/js/anchor.min.js"></script>
  24 <script src="https://docs.woltlab.com/5.3/js/toc.js"></script>
  25 <script src="https://docs.woltlab.com/5.3/js/customscripts.js"></script>
  26
  27 <link rel="shortcut icon" href="https://docs.woltlab.com/5.3/images/favicon.ico">
  28
  29 <link rel="alternate" type="application/rss+xml" title="woltlab.github.io" href="https://docs.woltlab.com/5.3feed.xml">
  30
  31     <script>
  32         $(document).ready(function() {
  33             // Initialize navgoco with default options
  34             $("#mysidebar").navgoco({
  35                 caretHtml: '',
  36                 accordion: true,
  37                 openClass: 'active', // open
  38                 save: false, // leave false or nav highlighting doesn't work right
  39                 cookie: {
  40                     name: 'navgoco',
  41                     expires: false,
  42                     path: '/'
  43                 },
  44                 slide: {
  45                     duration: 400,
  46                     easing: 'swing'
  47                 }
  48             });
  49
  50             $("#collapseAll").click(function(e) {
  51                 e.preventDefault();
  52                 $("#mysidebar").navgoco('toggle', false);
  53             });
  54
  55             $("#expandAll").click(function(e) {
  56                 e.preventDefault();
  57                 $("#mysidebar").navgoco('toggle', true);
  58             });
  59
  60         });
  61
  62     </script>
  63     <script>
  64         $(function () {
  65             $('[data-toggle="tooltip"]').tooltip()
  66         })
  67     </script>
  68
  69
  70 </head>
  71 <body>
  72   <!-- Navigation -->
  73 <nav class="navbar navbar-inverse navbar-fixed-top">
  74     <div class="container topnavlinks">
  75         <div class="navbar-header">
  76             <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
  77                 <span class="sr-only">Toggle navigation</span>
  78                 <span class="icon-bar"></span>
  79                 <span class="icon-bar"></span>
  80                 <span class="icon-bar"></span>
  81             </button>
  82             <a class="fa fa-home fa-lg navbar-brand" href="index.html">&nbsp;<span class="projectTitle"> WoltLab Suite 5.3 Documentation</span></a>
  83         </div>
  84         <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
  85             <ul class="nav navbar-nav navbar-right">
  86                 <!-- entries without drop-downs appear here -->
  87
  88
  89
  90                 <li><a href="https://www.woltlab.com" target="_blank">woltlab.com</a></li>
  91
  92
  93
  94
  95
  96                 <li><a href="https://github.com/WoltLab/WCF/" target="_blank">Code on github.com</a></li>
  97
  98
  99
 100                 <!-- entries with drop-downs appear here -->
 101                 <!-- conditional logic to control which topnav appears for the audience defined in the configuration file.-->
 102
 103
 104                 <!--comment out this block if you want to hide search-->
 105                 <li>
 106                     <!--start search-->
 107                     <div id="search-demo-container">
 108                         <input type="text" id="search-input" placeholder="search...">
 109                         <ul id="results-container"></ul>
 110                     </div>
 111                     <script src="https://docs.woltlab.com/5.3/js/jekyll-search.js" type="text/javascript"></script>
 112                     <script type="text/javascript">
 113                             SimpleJekyllSearch.init({
 114                                 searchInput: document.getElementById('search-input'),
 115                                 resultsContainer: document.getElementById('results-container'),
 116                                 dataSource: 'https://docs.woltlab.com/5.3/search.json',
 117                                 searchResultTemplate: '<li><a href="{url}" title="package.xml">{title}</a></li>',
 118                     noResultsText: 'No results found.',
 119                             limit: 10,
 120                             fuzzy: true,
 121                     })
 122                     </script>
 123                     <!--end search-->
 124                 </li>
 125             </ul>
 126         </div>
 127         </div>
 128         <!-- /.container -->
 129 </nav>
 130
 131
 132   <div class="container">
 133     <div class="col-lg-12">&nbsp;</div>
 134
 135     <div class="row">
 136       <div class="col-md-3">
 137
 138
 139
 140 <ul id="mysidebar" class="nav">
 141     <li class="sidebarTitle">WoltLab Suite 5.3</li>
 142
 143
 144
 145             <li>
 146                 <a href="#">Getting Started</a>
 147                 <ul>
 148
 149
 150
 151
 152                                 <li data-identifier="index"><a href="index.html">Introduction</a></li>
 153
 154
 155
 156
 157
 158
 159
 160
 161                                 <li data-identifier="getting-started_quick-start"><a href="getting-started_quick-start.html">Quick Start</a></li>
 162
 163
 164
 165
 166
 167                 </ul>
 168             </li>
 169
 170             <li>
 171                 <a href="#">PHP API</a>
 172                 <ul>
 173
 174
 175
 176
 177                                 <li data-identifier="php_pages"><a href="php_pages.html">Pages</a></li>
 178
 179
 180
 181
 182
 183
 184
 185
 186                                 <li data-identifier="php_database-objects"><a href="php_database-objects.html">Database Objects</a></li>
 187
 188
 189
 190
 191
 192
 193
 194
 195                                 <li data-identifier="php_database-access"><a href="php_database-access.html">Database Access</a></li>
 196
 197
 198
 199
 200
 201
 202
 203
 204                                 <li data-identifier="php_exceptions"><a href="php_exceptions.html">Exceptions</a></li>
 205
 206
 207
 208
 209
 210
 211
 212
 213                             <li class="subfolders">
 214                                 <a href="#">API</a>
 215                                 <ul>
 216
 217
 218
 219                                             <li data-identifier="php_api_caches"><a href="php_api_caches.html">Caches</a></li>
 220
 221
 222
 223
 224                                             <li data-identifier="php_api_comments"><a href="php_api_comments.html">Comments</a></li>
 225
 226
 227
 228
 229                                             <li data-identifier="php_api_cronjobs"><a href="php_api_cronjobs.html">Cronjobs</a></li>
 230
 231
 232
 233
 234                                             <li data-identifier="php_api_events"><a href="php_api_events.html">Events</a></li>
 235
 236
 237
 238
 239                                             <li data-identifier="php_api_form_builder"><a href="php_api_form_builder.html">Form Builder</a></li>
 240
 241
 242
 243
 244                                             <li data-identifier="php_api_package_installation_plugins"><a href="php_api_package_installation_plugins.html">Package Installation Plugins</a></li>
 245
 246
 247
 248
 249                                             <li data-identifier="php_api_user_activity_points"><a href="php_api_user_activity_points.html">User Activity Points</a></li>
 250
 251
 252
 253
 254                                             <li data-identifier="php_api_user_notifications"><a href="php_api_user_notifications.html">User Notifications</a></li>
 255
 256
 257
 258
 259                                             <li data-identifier="php_api_sitemaps"><a href="php_api_sitemaps.html">Sitemaps</a></li>
 260
 261
 262                                 </ul>
 263                             </li>
 264
 265
 266
 267
 268
 269                                 <li data-identifier="php_code-style"><a href="php_code-style.html">Code Style</a></li>
 270
 271
 272
 273
 274
 275
 276
 277
 278                                 <li data-identifier="php_apps"><a href="php_apps.html">Apps</a></li>
 279
 280
 281
 282
 283
 284
 285
 286
 287                                 <li data-identifier="php_gdpr"><a href="php_gdpr.html">GDPR</a></li>
 288
 289
 290
 291
 292
 293                 </ul>
 294             </li>
 295
 296             <li>
 297                 <a href="#">Languages, Templates & CSS</a>
 298                 <ul>
 299
 300
 301
 302
 303                                 <li data-identifier="view_languages"><a href="view_languages.html">Languages</a></li>
 304
 305
 306
 307
 308
 309
 310
 311
 312                                 <li data-identifier="view_templates"><a href="view_templates.html">Templates</a></li>
 313
 314
 315
 316
 317
 318
 319
 320
 321                                 <li data-identifier="view_css"><a href="view_css.html">CSS</a></li>
 322
 323
 324
 325
 326
 327                 </ul>
 328             </li>
 329
 330             <li>
 331                 <a href="#">JavaScript API</a>
 332                 <ul>
 333
 334
 335
 336
 337                                 <li data-identifier="javascript_general-usage"><a href="javascript_general-usage.html">General Usage</a></li>
 338
 339
 340
 341
 342
 343
 344
 345
 346                             <li class="subfolders">
 347                                 <a href="#">New API</a>
 348                                 <ul>
 349
 350
 351
 352                                             <li data-identifier="javascript_new-api_writing-a-module"><a href="javascript_new-api_writing-a-module.html">Writing a module</a></li>
 353
 354
 355
 356
 357                                             <li data-identifier="javascript_new-api_data-structures"><a href="javascript_new-api_data-structures.html">Data Structures</a></li>
 358
 359
 360
 361
 362                                             <li data-identifier="javascript_new-api_core"><a href="javascript_new-api_core.html">Core Functions</a></li>
 363
 364
 365
 366
 367                                             <li data-identifier="javascript_new-api_dom"><a href="javascript_new-api_dom.html">DOM</a></li>
 368
 369
 370
 371
 372                                             <li data-identifier="javascript_new-api_events"><a href="javascript_new-api_events.html">Event Handling</a></li>
 373
 374
 375
 376
 377                                             <li data-identifier="javascript_new-api_ajax"><a href="javascript_new-api_ajax.html">Ajax</a></li>
 378
 379
 380
 381
 382                                             <li data-identifier="javascript_new-api_dialogs"><a href="javascript_new-api_dialogs.html">Dialogs</a></li>
 383
 384
 385
 386
 387                                             <li data-identifier="javascript_new-api_browser"><a href="javascript_new-api_browser.html">Browser and Screen Sizes</a></li>
 388
 389
 390
 391
 392                                             <li data-identifier="javascript_new-api_ui"><a href="javascript_new-api_ui.html">User Interface</a></li>
 393
 394
 395                                 </ul>
 396                             </li>
 397
 398
 399
 400
 401
 402                                 <li data-identifier="javascript_legacy-api"><a href="javascript_legacy-api.html">Legacy API</a></li>
 403
 404
 405
 406
 407
 408
 409
 410
 411                                 <li data-identifier="javascript_helper-functions"><a href="javascript_helper-functions.html">Helper Functions</a></li>
 412
 413
 414
 415
 416
 417
 418
 419
 420                                 <li data-identifier="javascript_code-snippets"><a href="javascript_code-snippets.html">Code Snippets</a></li>
 421
 422
 423
 424
 425
 426                 </ul>
 427             </li>
 428
 429             <li>
 430                 <a href="#">Package Components</a>
 431                 <ul>
 432
 433
 434
 435
 436                                 <li class="active" data-identifier="package_package-xml"><a href="package_package-xml.html">package.xml</a></li>
 437
 438
 439
 440
 441
 442
 443
 444
 445                                 <li data-identifier="package_pip"><a href="package_pip.html">PIPs</a></li>
 446
 447
 448
 449
 450
 451                 </ul>
 452             </li>
 453
 454             <li>
 455                 <a href="#">Migration</a>
 456                 <ul>
 457
 458
 459
 460
 461                             <li class="subfolders">
 462                                 <a href="#">Migrating from WSC 5.2</a>
 463                                 <ul>
 464
 465
 466
 467                                             <li data-identifier="migration_wsc-52_php"><a href="migration_wsc-52_php.html">PHP API</a></li>
 468
 469
 470
 471
 472                                             <li data-identifier="migration_wsc-52_templates"><a href="migration_wsc-52_templates.html">Templates and Languages</a></li>
 473
 474
 475
 476
 477                                             <li data-identifier="migration_wsc-52_libraries"><a href="migration_wsc-52_libraries.html">Third Party Libraries</a></li>
 478
 479
 480                                 </ul>
 481                             </li>
 482
 483                             <li class="subfolders">
 484                                 <a href="#">Migrating from WSC 3.1</a>
 485                                 <ul>
 486
 487
 488
 489                                             <li data-identifier="migration_wsc-31_php"><a href="migration_wsc-31_php.html">PHP API</a></li>
 490
 491
 492                                 </ul>
 493                             </li>
 494
 495                             <li class="subfolders">
 496                                 <a href="#">Migrating from WSC 3.0</a>
 497                                 <ul>
 498
 499
 500
 501                                             <li data-identifier="migration_wsc-30_php"><a href="migration_wsc-30_php.html">PHP API</a></li>
 502
 503
 504
 505
 506                                             <li data-identifier="migration_wsc-30_javascript"><a href="migration_wsc-30_javascript.html">JavaScript API</a></li>
 507
 508
 509
 510
 511                                             <li data-identifier="migration_wsc-30_templates"><a href="migration_wsc-30_templates.html">Templates</a></li>
 512
 513
 514
 515
 516                                             <li data-identifier="migration_wsc-30_css"><a href="migration_wsc-30_css.html">CSS</a></li>
 517
 518
 519
 520
 521                                             <li data-identifier="migration_wsc-30_package"><a href="migration_wsc-30_package.html">Package Components</a></li>
 522
 523
 524                                 </ul>
 525                             </li>
 526
 527                             <li class="subfolders">
 528                                 <a href="#">Migrating from WCF 2.1</a>
 529                                 <ul>
 530
 531
 532
 533                                             <li data-identifier="migration_wcf-21_php"><a href="migration_wcf-21_php.html">PHP API</a></li>
 534
 535
 536
 537
 538                                             <li data-identifier="migration_wcf-21_templates"><a href="migration_wcf-21_templates.html">Templates</a></li>
 539
 540
 541
 542
 543                                             <li data-identifier="migration_wcf-21_css"><a href="migration_wcf-21_css.html">CSS</a></li>
 544
 545
 546
 547
 548                                             <li data-identifier="migration_wcf-21_package"><a href="migration_wcf-21_package.html">Package Components</a></li>
 549
 550
 551                                 </ul>
 552                             </li>
 553
 554
 555                 </ul>
 556             </li>
 557
 558             <li>
 559                 <a href="#">Tutorials</a>
 560                 <ul>
 561
 562
 563
 564
 565                                 <li data-identifier="tutorial_tutorial-series"><a href="tutorial_tutorial-series.html">Tutorial Series</a></li>
 566
 567
 568
 569
 570
 571                 </ul>
 572             </li>
 573
 574
 575 </ul>
 576
 577 <script>
 578 (function() {
 579     var sidebar = $('#mysidebar');
 580     var item = sidebar.find('.active');
 581     if (item.length === 0) {
 582         var parent = '';
 583         if (parent) {
 584             sidebar.find('li[data-identifier="' + parent + '"]').addClass('active');
 585         }
 586     }
 587
 588     sidebar.find(".active").parents('li').toggleClass("active");
 589 })();
 590 </script>
 591
 592       </div>
 593
 594       <div class="col-md-9">
 595         <div class="post-header">
 596    <h1 class="post-title-main">package.xml</h1>
 597 </div>
 598
 599
 600
 601 <div class="post-content">
 602
 603
 604
 605
 606
 607 <!-- this handles the automatic toc. use ## for subheads to auto-generate the on-page minitoc. if you use html tags, you must supply an ID for the heading element in order for it to appear in the minitoc. -->
 608 <script>
 609 $( document ).ready(function() {
 610   // Handler for .ready() called.
 611
 612 $('#toc').toc({ minimumHeaders: 0, listType: 'ul', showSpeed: 0, headers: 'h2,h3,h4' });
 613
 614 /* this offset helps account for the space taken up by the floating toolbar. */
 615 $('#toc').on('click', 'a', function() {
 616   var target = $(this.getAttribute('href'))
 617     , scroll_target = target.offset().top
 618
 619   $(window).scrollTop(scroll_target - 10);
 620   return false
 621 })
 622
 623 });
 624 </script>
 625
 626 <div id="toc"></div>
 627
 628
 629
 630   <p>The <code class="language-plaintext highlighter-rouge">package.xml</code> is the core component of every package.
 631 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.</p>
 632
 633 <h2 id="example">Example</h2>
 634
 635 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?xml version="1.0" encoding="UTF-8"?&gt;</span>
 636 <span class="nt">&lt;package</span> <span class="na">name=</span><span class="s">"com.example.package"</span> <span class="na">xmlns=</span><span class="s">"http://www.woltlab.com"</span> <span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span> <span class="na">xsi:schemaLocation=</span><span class="s">"http://www.woltlab.com http://www.woltlab.com/XSD/2019/package.xsd"</span><span class="nt">&gt;</span>
 637         <span class="nt">&lt;packageinformation&gt;</span>
 638                 <span class="nt">&lt;packagename&gt;</span>Simple Package<span class="nt">&lt;/packagename&gt;</span>
 639                 <span class="nt">&lt;packagedescription&gt;</span>A simple package to demonstrate the package system of WoltLab Suite Core<span class="nt">&lt;/packagedescription&gt;</span>
 640                 <span class="nt">&lt;version&gt;</span>1.0.0<span class="nt">&lt;/version&gt;</span>
 641                 <span class="nt">&lt;date&gt;</span>2016-12-18<span class="nt">&lt;/date&gt;</span>
 642         <span class="nt">&lt;/packageinformation&gt;</span>
 643
 644         <span class="nt">&lt;authorinformation&gt;</span>
 645                 <span class="nt">&lt;author&gt;</span>YOUR NAME<span class="nt">&lt;/author&gt;</span>
 646                 <span class="nt">&lt;authorurl&gt;</span>http://www.example.com<span class="nt">&lt;/authorurl&gt;</span>
 647         <span class="nt">&lt;/authorinformation&gt;</span>
 648
 649         <span class="nt">&lt;requiredpackages&gt;</span>
 650                 <span class="nt">&lt;requiredpackage</span> <span class="na">minversion=</span><span class="s">"3.0.0"</span><span class="nt">&gt;</span>com.woltlab.wcf<span class="nt">&lt;/requiredpackage&gt;</span>
 651         <span class="nt">&lt;/requiredpackages&gt;</span>
 652
 653         <span class="nt">&lt;excludedpackages&gt;</span>
 654                 <span class="nt">&lt;excludedpackage</span> <span class="na">version=</span><span class="s">"6.0.0 Alpha 1"</span><span class="nt">&gt;</span>com.woltlab.wcf<span class="nt">&lt;/excludedpackage&gt;</span>
 655         <span class="nt">&lt;/excludedpackages&gt;</span>
 656
 657         <span class="nt">&lt;instructions</span> <span class="na">type=</span><span class="s">"install"</span><span class="nt">&gt;</span>
 658                 <span class="nt">&lt;instruction</span> <span class="na">type=</span><span class="s">"file"</span> <span class="nt">/&gt;</span>
 659                 <span class="nt">&lt;instruction</span> <span class="na">type=</span><span class="s">"template"</span><span class="nt">&gt;</span>templates.tar<span class="nt">&lt;/instruction&gt;</span>
 660         <span class="nt">&lt;/instructions&gt;</span>
 661 <span class="nt">&lt;/package&gt;</span>
 662 </code></pre></div></div>
 663
 664 <h2 id="elements">Elements</h2>
 665
 666 <h3 id="package"><code class="language-plaintext highlighter-rouge">&lt;package&gt;</code></h3>
 667
 668 <p>The root node of every <code class="language-plaintext highlighter-rouge">package.xml</code> it contains the reference to the namespace and the location of the XML Schema Definition (XSD).</p>
 669
 670 <p>The attribute <code class="language-plaintext highlighter-rouge">name</code> is the most important part, it holds the unique package identifier and is mandatory.
 671 It is based upon your domain name and the package name of your choice.</p>
 672
 673 <p>For example WoltLab Suite Forum (formerly know an WoltLab Burning Board and usually abbreviated as <code class="language-plaintext highlighter-rouge">wbb</code>) is created by WoltLab which owns the domain <code class="language-plaintext highlighter-rouge">woltlab.com</code>.
 674 The resulting package identifier is <code class="language-plaintext highlighter-rouge">com.woltlab.wbb</code> (<code class="language-plaintext highlighter-rouge">&lt;tld&gt;.&lt;domain&gt;.&lt;packageName&gt;</code>).</p>
 675
 676 <h3 id="packageinformation"><code class="language-plaintext highlighter-rouge">&lt;packageinformation&gt;</code></h3>
 677
 678 <p>Holds the entire meta data of the package.</p>
 679
 680 <h4 id="packagename"><code class="language-plaintext highlighter-rouge">&lt;packagename&gt;</code></h4>
 681
 682 <p>This is the actual package name displayed to the end user, this can be anything you want, try to keep it short.
 683 It supports the attribute <code class="language-plaintext highlighter-rouge">languagecode</code> which allows you to provide the package name in different languages, please be aware that if it is not present, <code class="language-plaintext highlighter-rouge">en</code> (English) is assumed:</p>
 684
 685 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;packageinformation&gt;</span>
 686         <span class="nt">&lt;packagename&gt;</span>Simple Package<span class="nt">&lt;/packagename&gt;</span>
 687         <span class="nt">&lt;packagename</span> <span class="na">languagecode=</span><span class="s">"de"</span><span class="nt">&gt;</span>Einfaches Paket<span class="nt">&lt;/packagename&gt;</span>
 688 <span class="nt">&lt;/packageinformation&gt;</span>
 689 </code></pre></div></div>
 690
 691 <h4 id="packagedescription"><code class="language-plaintext highlighter-rouge">&lt;packagedescription&gt;</code></h4>
 692
 693 <p>Brief summary of the package, use it to explain what it does since the package name might not always be clear enough.
 694 The attribute <code class="language-plaintext highlighter-rouge">languagecode</code> is available here too, please reference to <a href="#packageName"><code class="language-plaintext highlighter-rouge">&lt;packagename&gt;</code></a> for details.</p>
 695
 696 <h4 id="version"><code class="language-plaintext highlighter-rouge">&lt;version&gt;</code></h4>
 697
 698 <p>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).</p>
 699
 700 <p>The possible keywords are:</p>
 701
 702 <ul>
 703   <li>Alpha/dev (both is regarded to be the same)</li>
 704   <li>Beta</li>
 705   <li>RC (release candidate)</li>
 706   <li>pl (patch level)</li>
 707 </ul>
 708
 709 <p>Valid examples:</p>
 710
 711 <ul>
 712   <li>1.0.0</li>
 713   <li>1.12.13 Alpha 19</li>
 714   <li>7.0.0 pl 3</li>
 715 </ul>
 716
 717 <p>Invalid examples:</p>
 718
 719 <ul>
 720   <li>1.0.0 Beta (keyword Beta must be followed by a number)</li>
 721   <li>2.0 RC 3 (version number must consists of 3 blocks of numbers)</li>
 722   <li>1.2.3 dev 4.5 (4.5 is not an integer, 4 or 5 would be valid but not the fraction)</li>
 723 </ul>
 724
 725 <h4 id="date"><code class="language-plaintext highlighter-rouge">&lt;date&gt;</code></h4>
 726
 727 <p>Must be a valid <a href="http://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> date, e.g. <code class="language-plaintext highlighter-rouge">2013-12-27</code>.</p>
 728
 729 <h3 id="authorinformation"><code class="language-plaintext highlighter-rouge">&lt;authorinformation&gt;</code></h3>
 730
 731 <p>Holds meta data regarding the package’s author.</p>
 732
 733 <h4 id="author"><code class="language-plaintext highlighter-rouge">&lt;author&gt;</code></h4>
 734
 735 <p>Can be anything you want.</p>
 736
 737 <h4 id="authorurl"><code class="language-plaintext highlighter-rouge">&lt;authorurl&gt;</code></h4>
 738
 739 <blockquote>
 740   <p>(optional)</p>
 741 </blockquote>
 742
 743 <p>URL to the author’s website.</p>
 744
 745 <h3 id="requiredpackages"><code class="language-plaintext highlighter-rouge">&lt;requiredpackages&gt;</code></h3>
 746
 747 <p>A list of packages including their version required for this package to work.</p>
 748
 749 <h4 id="requiredpackage"><code class="language-plaintext highlighter-rouge">&lt;requiredpackage&gt;</code></h4>
 750
 751 <p>Example:</p>
 752
 753 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;requiredpackage</span> <span class="na">minversion=</span><span class="s">"2.0.0"</span> <span class="na">file=</span><span class="s">"requirements/com.woltlab.wcf.tar"</span><span class="nt">&gt;</span>com.woltlab.wcf<span class="nt">&lt;/requiredpackage&gt;</span>
 754 </code></pre></div></div>
 755
 756 <p>The attribute <code class="language-plaintext highlighter-rouge">minversion</code> must be a valid version number as described in <a href="#version"><code class="language-plaintext highlighter-rouge">&lt;version&gt;</code></a>.
 757 The <code class="language-plaintext highlighter-rouge">file</code> attribute is optional and specifies the location of the required package’s archive relative to the <code class="language-plaintext highlighter-rouge">package.xml</code>.</p>
 758
 759 <h3 id="optionalpackage"><code class="language-plaintext highlighter-rouge">&lt;optionalpackage&gt;</code></h3>
 760
 761 <p>A list of optional packages which can be selected by the user at the very end of the installation process.</p>
 762
 763 <h4 id="optionalpackage-1"><code class="language-plaintext highlighter-rouge">&lt;optionalpackage&gt;</code></h4>
 764
 765 <p>Example:</p>
 766
 767 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;optionalpackage</span> <span class="na">file=</span><span class="s">"optionals/com.woltlab.wcf.moderatedUserGroup.tar"</span><span class="nt">&gt;</span>com.woltlab.wcf.moderatedUserGroup<span class="nt">&lt;/optionalpackage&gt;</span>
 768 </code></pre></div></div>
 769
 770 <p>The <code class="language-plaintext highlighter-rouge">file</code> attribute specifies the location of the optional package’s archive relative to the <code class="language-plaintext highlighter-rouge">package.xml</code>.</p>
 771
 772 <h3 id="excludedpackages"><code class="language-plaintext highlighter-rouge">&lt;excludedpackages&gt;</code></h3>
 773
 774 <p>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.</p>
 775
 776 <h4 id="excludedpackage"><code class="language-plaintext highlighter-rouge">&lt;excludedpackage&gt;</code></h4>
 777
 778 <p>Example:</p>
 779
 780 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;excludedpackage</span> <span class="na">version=</span><span class="s">"3.1.0 Alpha 1"</span><span class="nt">&gt;</span>com.woltlab.wcf<span class="nt">&lt;/excludedpackage&gt;</span>
 781 </code></pre></div></div>
 782
 783 <p>The attribute <code class="language-plaintext highlighter-rouge">version</code> must be a valid version number as described in the <a href="#version">&lt;version&gt;</a> section. In the example above it will be impossible to install this package in WoltLab Suite Core 3.1.0 Alpha 1 or higher.</p>
 784
 785 <h3 id="compatibility"><code class="language-plaintext highlighter-rouge">&lt;compatibility&gt;</code></h3>
 786 <div class="bs-callout bs-callout-info">Available since WoltLab Suite 3.1</div>
 787
 788 <div class="bs-callout bs-callout-warning">With the release of WoltLab Suite 5.2 the API versions were abolished. Instead of using API versions packages should exclude version <code class="language-plaintext highlighter-rouge">6.0.0 Alpha 1</code> of <code class="language-plaintext highlighter-rouge">com.woltlab.wcf</code> going forward.</div>
 789
 790 <p>WoltLab Suite 3.1 introduced a new versioning system that focused around the API compatibility and is intended to replace the <code class="language-plaintext highlighter-rouge">&lt;excludedpackage&gt;</code> instruction for the Core for most plugins.</p>
 791
 792 <p>The <code class="language-plaintext highlighter-rouge">&lt;compatibility&gt;</code>-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.</p>
 793
 794 <p>Example:</p>
 795
 796 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;compatibility&gt;</span>
 797         <span class="nt">&lt;api</span> <span class="na">version=</span><span class="s">"2018"</span> <span class="nt">/&gt;</span>
 798 <span class="nt">&lt;/compatibility&gt;</span>
 799 </code></pre></div></div>
 800
 801 <h4 id="existing-api-versions">Existing API versions</h4>
 802
 803 <table>
 804   <thead>
 805     <tr>
 806       <th>WoltLab Suite Core</th>
 807       <th>API-Version</th>
 808       <th>Backwards-Compatible to API-Version</th>
 809     </tr>
 810   </thead>
 811   <tbody>
 812     <tr>
 813       <td>3.1</td>
 814       <td>2018</td>
 815       <td>n/a</td>
 816     </tr>
 817   </tbody>
 818 </table>
 819
 820 <h3 id="instructions"><code class="language-plaintext highlighter-rouge">&lt;instructions&gt;</code></h3>
 821
 822 <p>List of instructions to be executed upon install or update. The order is important, the topmost <code class="language-plaintext highlighter-rouge">&lt;instruction&gt;</code> will be executed first.</p>
 823
 824 <h4 id="instructions-typeinstall"><code class="language-plaintext highlighter-rouge">&lt;instructions type="install"&gt;</code></h4>
 825
 826 <p>List of instructions for a new installation of this package.</p>
 827
 828 <h4 id="instructions-typeupdate-fromversion"><code class="language-plaintext highlighter-rouge">&lt;instructions type="update" fromversion="…"&gt;</code></h4>
 829
 830 <p>The attribute <code class="language-plaintext highlighter-rouge">fromversion</code> must be a valid version number as described in the <a href="#version">&lt;version&gt;</a> section and specifies a possible update from that very version to the package’s version.</p>
 831
 832 <div class="bs-callout bs-callout-warning">The installation process will pick exactly one update instruction, ignoring everything else. Please read the explanation below!</div>
 833
 834 <p>Example:</p>
 835
 836 <ul>
 837   <li>Installed version: <code class="language-plaintext highlighter-rouge">1.0.0</code></li>
 838   <li>Package version: <code class="language-plaintext highlighter-rouge">1.0.2</code></li>
 839 </ul>
 840
 841 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;instructions</span> <span class="na">type=</span><span class="s">"update"</span> <span class="na">fromversion=</span><span class="s">"1.0.0"</span><span class="nt">&gt;</span>
 842         <span class="c">&lt;!-- … --&gt;</span>
 843 <span class="nt">&lt;/instructions&gt;</span>
 844 <span class="nt">&lt;instructions</span> <span class="na">type=</span><span class="s">"update"</span> <span class="na">fromversion=</span><span class="s">"1.0.1"</span><span class="nt">&gt;</span>
 845         <span class="c">&lt;!-- … --&gt;</span>
 846 <span class="nt">&lt;/instructions&gt;</span>
 847 </code></pre></div></div>
 848
 849 <p>In this example WoltLab Suite Core will pick the first update block since it allows an update from <code class="language-plaintext highlighter-rouge">1.0.0 -&gt; 1.0.2</code>.
 850 The other block is not considered, since the currently installed version is <code class="language-plaintext highlighter-rouge">1.0.0</code>. After applying the update block (<code class="language-plaintext highlighter-rouge">fromversion="1.0.0"</code>), the version now reads <code class="language-plaintext highlighter-rouge">1.0.2</code>.</p>
 851
 852 <h4 id="instruction"><code class="language-plaintext highlighter-rouge">&lt;instruction&gt;</code></h4>
 853
 854 <p>Example:</p>
 855
 856 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;instruction</span> <span class="na">type=</span><span class="s">"objectTypeDefinition"</span><span class="nt">&gt;</span>objectTypeDefinition.xml<span class="nt">&lt;/instruction&gt;</span>
 857 </code></pre></div></div>
 858
 859 <p>The attribute <code class="language-plaintext highlighter-rouge">type</code> specifies the instruction type which is used to determine the package installation plugin (PIP) invoked to handle its value.
 860 The value must be a valid file relative to the location of <code class="language-plaintext highlighter-rouge">package.xml</code>.
 861 Many PIPs provide default file names which are used if no value is given:</p>
 862
 863 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;instruction</span> <span class="na">type=</span><span class="s">"objectTypeDefinition"</span> <span class="nt">/&gt;</span>
 864 </code></pre></div></div>
 865
 866 <p>There is a <a href="package_pip.html">list of all default PIPs</a> available.</p>
 867
 868 <div class="bs-callout bs-callout-warning">Both the <code class="language-plaintext highlighter-rouge">type</code>-attribute and the element value are case-sensitive. Windows does not care if the file is called <code class="language-plaintext highlighter-rouge">objecttypedefinition.xml</code> but was referenced as <code class="language-plaintext highlighter-rouge">objectTypeDefinition.xml</code>, but both Linux and Mac systems will be unable to find the file.</div>
 869
 870 <p>In addition to the <code class="language-plaintext highlighter-rouge">type</code> attribute, an optional <code class="language-plaintext highlighter-rouge">run</code> attribute (with <code class="language-plaintext highlighter-rouge">standalone</code> 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 <code class="language-plaintext highlighter-rouge">memory_limit</code> or <code class="language-plaintext highlighter-rouge">max_execution_time</code>:</p>
 871
 872 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;instruction</span> <span class="na">type=</span><span class="s">"file"</span> <span class="na">run=</span><span class="s">"standalone"</span> <span class="nt">/&gt;</span>
 873 </code></pre></div></div>
 874
 875 <h4 id="void"><code class="language-plaintext highlighter-rouge">&lt;void/&gt;</code></h4>
 876
 877 <p>Sometimes a package update should only adjust the metadata of the package, for example, an optional package was added.
 878 However, WoltLab Suite Core requires that the list of <code class="language-plaintext highlighter-rouge">&lt;instructions&gt;</code> is non-empty.
 879 Instead of using a dummy <code class="language-plaintext highlighter-rouge">&lt;instruction&gt;</code> that idempotently updates some PIP, the <code class="language-plaintext highlighter-rouge">&lt;void/&gt;</code> tag can be used for this use-case.</p>
 880
 881 <p>Using the <code class="language-plaintext highlighter-rouge">&lt;void/&gt;</code> tag is only valid for <code class="language-plaintext highlighter-rouge">&lt;instructions type="update"&gt;</code> and must not be accompanied by other <code class="language-plaintext highlighter-rouge">&lt;instruction&gt;</code> tags.</p>
 882
 883 <p>Example:</p>
 884
 885 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;instructions</span> <span class="na">type=</span><span class="s">"update"</span> <span class="na">fromversion=</span><span class="s">"1.0.0"</span><span class="nt">&gt;</span>
 886         <span class="nt">&lt;void/&gt;</span>
 887 <span class="nt">&lt;/instructions&gt;</span>
 888 </code></pre></div></div>
 889
 890
 891     <div class="tags">
 892
 893     </div>
 894
 895
 896
 897 </div>
 898
 899       </div>
 900     </div>
 901   </div>
 902
 903   <div class="footerBox">
 904     <div class="container">
 905       <div class="footerBoxLeft">
 906
 907         <a target="_blank" href="https://github.com/woltlab/woltlab.github.io/blob/master/pages/package/package_package-xml.md" class="btn btn-default githubEditButton no_icon" role="button"><i class="fa fa-github fa-lg"></i> Edit on GitHub</a>
 908         <p>Site last generated: Mar 5, 2021</p>
 909       </div>
 910       <div class="footerBoxRight">
 911         <a class="no_icon" href="https://www.woltlab.com"><img src="https://docs.woltlab.com/5.3/images/woltlab-black.png" srcset="https://docs.woltlab.com/5.3/images/woltlab-black@2x.png 2x" height="40" width="204" alt=""></a>
 912       </div>
 913     </div>
 914   </div>
 915
 916   <div class="pageFooter">
 917     <div class="container">
 918       &copy; 2001 ‐ 2021 <a class="no_icon" href="https://www.woltlab.com">WoltLab GmbH</a>. All rights reserved. | <a class="no_icon" href="https://www.woltlab.com/legal-notice/">Legal Notice</a> | <a class="no_icon" href="https://www.woltlab.com/privacy-policy/">Privacy Policy</a>
 919     </div>
 920   </div>
 921 </body>
 922
 923 </html>