The Aukyla Application Package Format

Intro

Aukyla Application Packages (AAPs) are primarily used for installing or updating applications in the Aukyla Platform, but can in fact install any kind of content, like plugins, translations, and updates to the Aukyla Platform itself. AAPs are basically Zip files, containing a special file called package.xml describing the package contents, and the files making up the contents itself.

To create your own application package, just create the file package.xml and put in some meta-data, so that the file looks like this:

<?xml version="1.0" encoding="utf-8"?>
<package>
        <shortName>my_package</shortName>
</package>

You can then, from that same directory, run the following command:

# create_package.php
Created package my_package.aap.

This will have resulted in a totally useless, but installable package.

Meta-data

In the package we created, we have only defined one bit of meta-data, namely the short name of the package. Here is an overview of all the meta-data that can be defined:

  • shortName. The short name of the package, which should be unique across all packages. It's advised to not use spaces or special characters in the short name. This is the only meta-data element that is really required.
  • name. This is the regular name of the package. Just use the name of your application here.
  • description. If you feel like it, you can give a more lengthy description of what the package does or contains here.
  • supplier. Not unimportant, this element specifies the name of the author or supplier of the package.
  • version. The version number of the package. The version is not important for the package itself, but may be used by other packages which specify a dependency on this package. Version numbers are parsed into the form major.minor.patch, where missing parts are assumed to be 0. So a version number of "2.0" is equal to the version numbers "2" and "2.0.0".

Dependencies

It is not uncommon for a package to rely on functionality provided by other packages. Therefore, you can specify which other packages, and which versions of these packages, should be installed before a package itself is allowed to be installed. This is done by creating an element dependencies, in which you can create a dependency element for every dependency the package has. Within the dependency element, you can specify the package on which your package depends, and the version of the package that should be installed. Use the following elements for this:

  • package. Here you should specify the short name of the package on which your package depends.
  • minVersion. The minimum version of the package that should be installed. If ommitted, there's no lower limit to which version of the package may be installed.
  • maxVersion. The maximum version of the package that may be installed. If ommitted, there's no upper limit to which version of the package may be installed.

For example, a package which depends on at least version 2.1 of the Aukyla Platform, can specify its dependency as follows:

        <dependencies>
                <dependency>
                        <package>platform</package>
                        <minVersion>2.1</minVersion>
                </dependency>
        </dependencies>

Files

The main part of the package will logically be its contents. The file package.xml should register all the files which are in the package, and any file that's not in the file package.xml will not be installed (and won't even be included in the package by the create_package.php utility).

To specify which files are in the package, use the files element. Within this element, use a file element for every file in the package. The value of the element should be the relative path to the file.

For example, a package which contains a single file called MyFrontend.php in the subdirectory plugins/Frontends, can specify this file as follows:

        <files>
                <file>plugins/Frontends/MyFrontend.php</file>
        </files>

In addition, two attributes can be specified on the file element. These are the executable and update attributes. The executable attribute can take the following values:

  • yes. Indicates that this file should be executable. Use this for scripts that you want to be executable from the command-line.
  • no. The file is not executable (the default).
  • cgi. The file should be made executable only if installed within a CGI environment. Use this for scripts that should be directly accessible from the webserver. If the file is installed within a CGI environment, the Aukyla Platform will also automatically prepend the correct shebang for the script, so you should not specify the shebang yourself inside the script file.

The update attribute specifies how the file should be handled when doing an update rather than a clean installation. It can take the following values:

  • yes. The file is always installed during an update, overwriting any older versions (the default).
  • no. The file should only be installed during a clean installation, and never during an update. Useful for files that should not be overwritten.
  • if-not-exists. The file should only be installed if it did not yet exist. Useful for data files that may not have existed in a previous version of the package. (new in version 2.1 of the Aukyla Platform)
  • config. Indicates that the file is a configuration file (which should have the extension .conf). During an update the new version of the configuration file will be installed, but the old version will be read and all its variables will be imported into the new version.
  • run-once. The file will never be installed, but only run once. This can be useful to trigger scripts that convert data from an old format to a new file. Note that this is for update purposes only, and the script will not be run when doing a clean installation. (new in version 2.1 of the Aukyla Platform)

Resources

Resources are just plain files that will be made available publicly from the webserver. Examples are CSS and JavaScript files and images. Resources are placed inside the package in the subdirectory htdocs/resources and will be installed in the resources directory in the document root of the webserver.

Resources are specified in the same way as files are specified, except that the files and file elements are replaced by the elements resources and resource, respectively. The specified path should be relative to the htdocs/resources directory, rather than the root of the package. No attributes are supported on the resource element.

For example, a package which has a resource file called layout.css in the subdirectory htdocs/resources/plugins/Frontends/MyFrontend, can specify this file as follows:

        <resources>
                <resource>plugins/Frontends/MyFrontend/layout.css</resource>
        </resources>

Modules

If the package contains add-on modules (which are stored in the plugins/Modules subdirectory), you should specify some additional meta-data about them, so they can be activated. To specify the modules in your package, use the modules element and for each module use a module element. Within the module element, you can specify the following elements:

  • shortName, name and description. Just like the meta-data for the package, but now for the specific module. The short name should match the filename of the module, without the .php extension.
  • enabledByDefault. This should have the value "true" or "false" (the default). If set to true, the module will be directly enabled upon package installation.
  • defaultPriority. The priority is a 3-digit number specifying the order in which modules are loaded. Modules with a lower priority are loaded before modules with a higher priority. The order in which modules with equal priority are loaded is unspecified. The normal priority is "010" and there's a convention that no module with priority "000" should instantiate the Login class.

For example, a package that wishes to install a Logger module that's enabled by default and which should be able to log signals comming from the Login class, could specify this module as follows:

        <files>
                <file>plugins/Modules/Logger.php</file>
        </files>
        <modules>
                <module>
                        <shortName>Logger</shortName>
                        <name>Logger Module</shortName>
                        <description>A module logging various signals</description>
                        <enabledByDefault>true</enabledByDefault>
                        <defaultPriority>000</defaultPriority>
                </module>
        </modules>

Final notes

The tutorial How to write your own Aukyla Frontend also walks through the creation of an Aukyla Application Package, and you can download and unzip the package created in the tutorial to examine the contents of a real package. If you want some more real-life examples, you can also inspect the AAPs of the Aukyla Platform itself and those of ADMS.

If you have any remaining questions, please do not hesitate to contact us.

This site is powered by Aukyla SiteManager. Administrators can log in.