17. Extension Packages
Prev |  |

## 17. Extension Packages

TrEd extension packages are used to package related annotation modes (macros and Perl modules they use), stylesheets, resources (e.g. PML schemas), XSLT transformations, etc. to TrEd users. Extension pacakges are deployed using package repositories on the web. The users can install extensions from TrEd by adding the URL to the repository to a list of repositories using a Repository Manager accessible from the Extension Manager and selecting the extensions of their choice. Extensions can depend on other extensions and the TrEd installer attempts to resolve the dependencies automatically.

The following sections describe in detail the content and format of an extension package and the format of a web repository.

### 17.1. Extension Package Format and Content

An extension package is simply a ZIP file that among other files contains in the root directory a PML file named `package.xml` conforming to the PML schema `tred_extension_schema.xml` that can be found in the `resources` subdirectory of a TrEd installation. The information provided in the `package.xml` file is used by the Extension Manager to present the extension to the user. The `package.xml` file can look like this:

    <?xml version="1.0" encoding="UTF-8"?>
    <tred_extension xmlns="http://ufal.mff.cuni.cz/pdt/pml/">
      <head>
        <schema href="tred_extension_schema.xml"/>
      </head>
      <pkgname>sample_extension</pkgname>
      <title>A Sample TrEd Extension</title>
      <version>3.1</version>
      <copyright year="2008">Petr Pajas</copyright>
      <description>This is extension provides an example of how a TrEd extension might look like.</description>
      <require>
        <extension name="pdt20" min_version="1.0" href="http://ufal.mff.cuni.cz/~pajas/tred/extensions/pdt20"/>
        <extension name="padt" min_version="1.0" href="http://ufal.mff.cuni.cz/~pajas/tred/extensions/padt"/>
      </require>
    </tred_extension>

An extension is uniquely identified by its short name (identifier), which in the above example is `sample_extension`. Extension creators should attempt to avoid name colisions by choosing dinstinctive names. To the users, the extension is presented by their long name, that can be a short descriptive phrase (`A Sample TrEd Extension` in the case above). Extensions are versioned so that TrEd can offer the user upgrades if newer version of an installed extension becomes available in some repository. The `package.xml` file should further contain a description element (which may contain a short paragraph of unformatted text) and copyright information. Finally, a list of other extensions required by this extension may be given (in our example they are extensions `pdt20` and `padt` both in versions at least 1.0); optionally, an URL can be given to provide a direct link to the required extension for the case when the user does not have the corresponding repositories configured.

Beside the `package.xml` file, an extension can contain arbitrary files, some of which, however, have special meaning to TrEd:

- If the extension contains a directory `contrib`, TrEd looks for all files named `contrib.mac` located either directly in the `contrib` directory or in its first level subdirectories and attempts to loads these files as files with macros. Also, an

      #include <contrib/filename>

  directive used in a macro file of any extension looks for `contrib/filename` in all (!) extensions. To avoid filename clashes, it is therefore recommended to put `contrib.mac` and all other macro files of an extension to a subdirectory (usually named after the extension) of `contrib`, e.g. to create the directory structure like this:

      contrib/
      contrib/sample_extension/
      contrib/sample_extension/contrib.mac
      contrib/sample_extension/sample_macros1.mak
      contrib/sample_extension/sample_macros2.mak

  Then

      #include <contrib/sample_extension/sample_macros2.mak>

  can be used to include the macro file `sample_macros2.mak` provided by this extension from a macro file of some other extension.

- If the package contains a directory named `libs`, TrEd adds this directory to the Perl module search path (`@INC`).

- If the package contains a directory named `resources`, TrEd adds this directory to its list of resource paths (see resourcePath configuration option).

- If the package contains a directory named `stylesheets`, TrEd adds this directory to its list of directories to load stylesheets from. Each file in this directory should be a text file containing a TrEd stylesheet in the TrEd stylesheet syntax. The name of the stylesheet in TrEd is the same as the basename of the file. If a similarly named stylesheet is already loaded (e.g. from some directory appearing earlier in the stylesheet directory list), the stylesheet is ignored. If the stylesheet name contains non-ascii or non-alphanumeric characters, they must be http://search.cpan.org/~pajas/Treex-PML/lib/>URI-escaped. If the user modifies a stylesheet loaded from an extension, TrEd saves the modified version into the user's private stylesheet directory `~/tred.d/stylesheets`, which always appears first in the stylesheet directory list, so the modified version has precedence.

- If the package contains a directory named `documentation` and this directory contains an HTML or XHTML file named `index.pm`, TrEd adds a menu item Help → Extension manuals → `extension name` that opens this file in the default browser. This index file can be just a table of contents, pointing to other files within the extension via relative URLs.

- If the resource folder contains a PML file name `pmlbackend_conf.inc` with transformation rules for the PML_backend, the transformatino rules are prepended to the list of transformation rules contained in `pmlbackend_conf.xml` and are used as described in section Section 16.6.2, “Support for non-PML XML-based formats”.

### 17.2. Extension Repository

Extension repository is a local directory or a directory located on the web accessible by HTTP prococol that contains the following files:

- a file named `extensions.lst` containing a list of short package names of extensions available in this repository. Each extension name must be given on a separate line.

- for each package listed in `extensions.lst`, a ZIP file ``pkgname`.zip` where `pkgname` is the short name of the extension, containing the extension data (and most notably the file ``package.xml``).

- for each package listed in `extensions.lst` a subdirectory ``pkgname`` (where ``pkgname`` is the name of the extension) containing a file ``package.xml`` (described above) which should be exactly same as the one contained in the ZIP package of the extension.

When TrEd reads the content of a repository, it first fetches the file `extensions.lst` and for each entry listed there it requests the file ``pkgname`/package.xml`. If the user chooses to install or upgrade a given package, the ZIP file ``pkgname`.zip` is requested and extracted to a subdirectory `.tred.d/extensions/`pkgname`/` in the user's home directory (`Application Data` on Windows).

### 17.3. Developing Extensions

The file `devel/pack_extension.sh` contains a Bash script that simplifies creating an extension package from a given directory, copying the result to a repository directory, and incrementing package versions. It takes two arguments: a path to a directory with the extension (containing the `pacakge.xml` file and other files pertaining by the extension) and a path to a directory containing a package repository. The script performs the following steps:

- Check that there is a valid `pacakge.xml` file (validation requires the script `pml_validate` from the PML Toolkit).

  compress the the content of the extension directory into a ZIP archive

  check if a similarly named ZIP file is already contained in the repository:

  - If not, it creates an entry in `extensions.lst` in the repository, copies the ZIP file to the repository and creates there the corresponding subfolder with the `package.xml` file.

  - If yes, it compares the MD5 checksum of the newly created ZIP file with the one already in the repository. If the MD5s are equal, it does nothing. Otherwise the least significant part of the package version is incremented in the file `package.xml` in the extension directory, a new ZIP file is created with the updated `package.xml` and both the ZIP and the `package.xml` are copied to the repository directory.

### Tip

To test a development version of an extension from a live working copy, one can e.g. go to the `~/.tred.d/extensions` directory and replace the subdirectory corresponding to the (relevant part of the) extension with a symlink to the working copy. Using a symlink rather than a direct copy protects the actual working copy from being deleted by TrEd if `Uninstall` is performed on the extension from the Extension Manager (only the symlink gets deleted).

Prev |  |
16. I/O backends | Home | ToC |