The Qt Jambi Deployment Specification

The Qt Jambi deployment specification is a simple XML file, named qtjambi-deployment.xml, which is located in the root of a platform archive. It contains a list of all libraries that the platform archive contains and which of them should be loaded automatically and which should only be unpacked. The details of the deployment specification is provided here primarly as background information for the curious reader. For normal deployment scenarios, its contents is automatically generated by the ant build tasks described further down in this document.

The qtjambi-deploy Element

qtjambi-deploy This is the root element of the XML file. It is used to identify the validity of the XML file and to describe which target system this file is meant for. It can have the following attributes:

system; The system, either "win32", "win64", "linux32", "linux64" or "macosx".

If the system attribute does not match the current running system, the entire platform archive is igonred, and none of its contents is loaded.

The cache Element

cache The platform archive will be unpacked into a temporary directory so that the process can load the native libraries. To avoid that libraries conflicts between libraries compiled with different compilers or for different target systems, such as windows 32-bit and windows 64-bit, we recommend specifying a unique cache key for your own deployment specifications when building your own platform archives. The cache is specified like this:

<qtjambi-deploy ...>
  <cache key="my.unique.key" />

The library Element

library The library element is used to describe a library in the platform arhive. A library is listed with its full name and path inside the platform archive and will be unpacked to the temporary directory with its directory structure intact.

The library element can have the following attributes:

name; This attribute is the full path and filename of the library inside the platform archive.
load; This attribute describes how the library should be loaded.
- never; The library is only unpacked, and any attempt to explicitly load it will yield a runtime exception. Typically used for plugins.
- yes; The library is loaded when it is unpacked. This is typically used for runtime libraries, except the Visual Studio 2005 and 2008 runtimes which \b must only ever be unpacked, never loaded.
- default; The library is unpacked, and lazily loaded based on calls to {Utilities.loadJambiLibrary()} and Utilities.loadLibrary().

Elements are added to the deployment spec in the following manner:

<qtjambi-deploy ...>
  <library name="bin/mylib.dll" />
  ...

The plugin Element

plugin The plugin element describes which directories in the unpacked platform archive should be treated as a root for Qt C++ plugins. Each entry correponds to a call to QApplication.addLibraryPath(). Elements are added to the deployment specification in the following manner:

<qtjambi-deploy ..>
  <plugin path="thePluginDirectory" />
  ...

Creating Platform Archives using ANT

This document describes how to make use of Qt Jambi's ant specific classes to help build a platform specific JAR file for your project.

The tasks are available in the ant-qtjambi.jar file in the classes com.trolltech.tools.ant.InitializeTask and com.trolltech.tools.ant.PlatformJarTask. To make use of the task in an ant build script you need the following commands:

    <taskdef name="qtjambi-initialize"
             classpath="ant-qtjambi.jar"
             classname="com.trolltech.tools.ant.InitializeTask"/>
    <taskdef name="qtjambi-platform-jar"
             classpath="ant-qtjambi.jar"
             classname="com.trolltech.tools.ant.PlatformJarTask"/>

Initialization Task

The InitializeTask's primary purpose is to define a set of variables to aid the PlatformJarTask. It should be run as early as possible, in the following manner:

<qtjambi-initialize verbose="true" />

Input Parameters

verbose; Can be true or false. When set to true, the task will print out the specific variables it detects.

Variables

Below is a list of the various variables defined by the task. They are accessible throughout the ant build script, after the task has been completed. To access the properties use the default ant syntax, for instance:

  <jar destfile="qtjambi-${qtjambi.version}.jar">

to access the property qtjambi.version.

qtjambi.osname; This variable contains the operating system name, such as win32 or linux64
qtjambi.libsubdir; This variable contains the default subdirectory used for libraries for the current operating system, typically bin for windows and \c lib for other platforms. \o \c qtjambi.qtdir; The location of Qt, picked up from the environment variable QTDIR. If QTDIR is not available when the task is running an error will be thrown.
qtjambi.qmakespec; A variable used for Qt and qmake to decide buildsystem, picked up from the environment variable QMAKESPEC or from the compiler currently available in PATH.
qtjambi.version; The version of Qt Jambi, on the form "Major.Minor.Patch_buildnumber", for instance 4.4.0_01.
qtjambi.compiler; The compiler used to compile the C++ parts of Qt Jambi.
qtjambi.vsinstalldir; With MSVC 2005 and 2008 only. The location where Visual Studio is installed. This is picked up from the environment variable VSINSTALLDIR and is required if the MSVC 2005 or 2008 compilers are in use. For internal use only.
qtjambi.vsredistdir; With MSVC 2005 and 2008 only. The location describing where the Visual Studio runtimes are available. For internal use only.

Platform Archive Task

The purpose of the platform archive task is to register input libraries and copy them to an output folder, along with any dependent system runtime libraries. It also generates a deployment specification for the libraries so the content of the output folder simply can be packed into a qtjambi platform archive used for loading.

The benefit of using this task to generate the deployement spec and the directory structure is that this task will handle the problematic aspects of Microsoft Visual Studio 2005 and 2008, manifest based, deployment for instance.

Attributes

cacheKey; This parameter specifies the cache key to be used in the deployment specification.
outdir; This parameter specifies the base directory used for the qtjambi-deployment.xml and the libraries that are to be included in the platform jar.
syslibs; This parameter specifies if the task should handle system libs or not. The value can be either "auto" or "none", where "auto" is the default.

Library Entries

The platform specification is built up from multiple library entries. Library entries are specified in the followin manner:

<qtjambi-platform-jar>
  <library name="..." ...>

The library entry can have the following attributes:

name; This attribute describes the name of the library, without the platform specific suffix and extension.
type; This attribute describes the type of library and can be:
- qt; A Qt C++ library.
- qtjambi; A Qt Jambi or normal JNI native library.
- plugin; A Qt C++ plugin library.
rootDir; This attribute describes the root directory for where to search for the directory.
subdir; This attribute contains the subdirectory relative from rootDir to where the library is located. By default this value is set to the typical platform specific library directory which is bin on Windows and lib for other platforms. The library will maintain this directory structure in the final platform archive.
load; This attribute describes when and how the library should be loaded if at all. The possible values are:
- never; The library cannot be loaded using Utilities.loadJambiLibrary() or Utilities.loadLibrary(). This value is normally used for plugins.
- yes; The library is automatically loaded when the platform archive is first unpacked by Qt Jambi. This is normally used for system libraries, so the user rarely has to use it.
- default; The library can and will be loaded using calls to {Utilities.loadJambiLibrary()} or Utilities.loadLibrary(). This is the default value.

Plugin Entries

In addition to containing library entries, a platform archive can contain a list a plugin paths that are automatically added, so Qt knows where to search for Qt C++ plugins. Each plugin entry will end up result in a call to QApplicaiton.addLibraryPath() when the platform archive is loaded. For instance:

   <qtjambi-platform-jar ...>
     <library name="qjpeg"
              type="plugin"
              subdir="plugins/imageformats"
              rootDir="${qtjambi.qtdir}"
              load="never"/>
     <plugin path="plugins" />

Trademarks

Qt Jambi 4.5.2_01