|  | Home · Overviews · Examples |

# Deploying Qt Jambi Applications

Java provides a number of different features which makes it easier to deploy applications, such as the Web Start technology, Java Archives (`.jar` files) and, of course, the virtual machine that enables you to compile your application to bytecode once and run on all architectures.

The apparent challenge when deploying Qt Jambi applications is that Qt Jambi makes use of Qt's C++ libraries which means that platform dependent code must be distributed in addition to the platform independent bytecode. Qt Jambi provides a solution - all you have to do is to include the native libraries in a JAR bundle.

To include resources, the programmer must follow a particular syntax since Qt Jambi provides its own resource system. But note that this system makes it easy to access any kind of resource (e.g., pixmaps, translation files and xml data files), no matter whether they are located, directly on the disk or in a JAR bundle.

We will first take a look at how Qt Jambi loads native libraries into the application, and how to include resources using Qt Jambi's resource system. Then we will see how to create an executable `.jar` file. We then explain how a Qt Jambi application can be deployed using the Web Start technology. For an example, please take a look at our own Web Start application, "The Qt Jambi Examples and Demos Launcher".

- Resolving Native Libraries
- Including Resources
- Including Plugins
- Creating an Executable .jar File

- Creating a .jar file for MSVC 2005

- Creating a Web Start Application

## Resolving Native Libraries

The Qt Jambi native libraries are located in the `lib` directory in the Qt Jambi directory. If you have a prebuilt package, the Qt libraries will also be available there. In case you have a source package, you will find the necessary Qt libraries in the `lib` directory in the Qt directory.

Qt Jambi searches the classpath for libraries. So to distribute the libraries with your application, you can simply include them in a JAR bundle, which is then placed in the classpath.

The Qt and Qt Jambi native libraries may depend on other libraries, which must be distributed as well. It is possible to specify dependent libraries by listing them in a file called `qt_system_libs`, which should be located somewhere in the classpath root. One can also specify the libraries on the command line with the `com.trolltech.qt.systemlibraries` variable, which should contain paths to the libraries. The libraries are loaded in the order listed in the file or on the command line.

We present a table with the necessary libraries below:

Platform | Native Libraries
--- | ---
MSVC 6.0 | msvcp60.dll and msvcr60.dll
MSVC 2002 | msvcr70.dll and msvcp70.dll
MSVC 2003 | msvcr71.dll and msvcp71.dll
MSVC 2005 | Microsoft Visual Studio 2005 introduces manifest files as a way of describing dependencies between dll's. This restricts the way binaries can be deployed. Manifest based runtime libraries will in this case need to be available for Qt Jambi to load. These files are not available by default on Windows Vista, Windows XP nor Windows 2000. This is solved by either: Installing manifest based runtimes on the target system using Microsoft's Visual Studio Redistributable Package. At the time of writing this is possible using the application "vcredist_x86.exe", which is provided on the `microsoft.com` websites. Redistribute the runtime libraries provided in the Qt Jambi package or in your own Visual Studio version along with their manifest next to every .dll. The redistributables can be placed either directly next to the Qt Jambi .dll's or in a subdirectory called Microsoft.VC80.CRT. For projects with .dll's in multiple folders, such as the Qt Jambi plugins in the plugin sub directory, the files need to be duplicated in all places. Note: Since Qt treats all .dll files in a plugin folder as a plugin it will try to load the the runtime libraries as plugins. To prevent this, it is recommended that the redistributable runtime libraries are placed in a Micrsoft.VC.CRT sub directory under each plugin. See the Creating a .jar file for MSVC 2005 section for an example.
Open Source Windows Version | mingwm10.dll
Linux | libstdc++.so. Since there are different versions of this library, you need to ship the library that the application is linked against. You can check this with the `ldd` utility.
Mac OS X | No libraries are required on Mac OS X.

There are also tools on each platform for checking library dependencies. UNIX systems has the `ldd` utility, Mac OS X provides `oTool`. Windows has no standard tool, but a good freely available application is the Dependency Walker. MSVC includes its own application: `depends`.

If you still have problems, you can set the `com.trolltech.qt.verbose-loading` system property, in which case Qt Jambi will report which libraries are missing.

The Qt Jambi Generator and Custom Libraries

Qt Jambi also supports distribution of custom native libraries using the same approach as for regular libraries. This makes it possible to ship applications based on Java and C++, both as executable `.jar` files and using the Web Start technology.

To generate code that maps a C++ library onto an equivalent Java API, Qt Jambi provides its own generator. For more information, please see the Qt Jambi generator documentation.

## Including Resources

Qt Jambi provides a complete file system abstraction that allows a uniform syntax (based on the Java classpath) for accessing resources, whether they are located directly on the disk or in a JAR bundle. While the standard Java API only supports accessing resources in an undocumented subset of its file I/O operations (which does not include the `java.io.File` class), Qt Jambi allows resources to be used wherever a file name is expected. Resources are identified by a `classpath`: prefix.

Note that it is also possible to load resources as raw data:

        QFile file = new QFile("classpath:images/fileopen.png");
        file.open(QIODevice.OpenModeFlag.ReadOnly);
        QByteArray rawData = file.readAll();

To include resources in your distribution, all you have to do is to ensure that the application follows the Qt Jambi syntax for accessing resources and make the resources available by adding them to your JAR bundle.

## Including Plugins

In addition to the Qt native libraries, you need to deploy Qt plugins, such as JPEG support and SQL drivers. See the plugins document for more information about Qt plugins.

The Qt plugins are located in the `plugins` directory in the directory where Qt Jambi is installed. They are placed in subdirectories according to type, e.g., SQL drivers and image formats.

Plugins are deployed in a `.jar` file following the same directory structure as in the Jambi installation directory. When running the application, the `com.trolltech.qt.pluginjars` system property must be set to contain the path to the `.jar` file containing the plugins. The plugins do not need to have their own file, so it is, for instance, possible to deploy them in the same file as your application.

## Creating an Executable .jar File

To deploy Qt Jambi applications using the executable `.jar` file approach is straight forward:

        jar mcf <manifest file> myApplication.jar <my class files>
                         <my resources> <native libraries> <plugins>

Simply put all resources, native libraries, plugins ,and application `.class` files into one single `.jar` file. Remember to add a manifest file to make the file executable and a qt_system_libs for the system libraries. Note that all native libraries must be placed in the root directory in the file.

For instance, if you were to create a file for the Application Example, the manifest file will look like this:

        Main-Class: com.trolltech.examples.Application

The qt_system_libs file on Linux will read:

        libstdc++.so.5

The necessary system libraries on other platforms are given in Resolving Native Libraries.

Assuming your current directory is the Jambi directory, you can create a `.jar` file on a Linux system with:

        jar mcf Manifest.text application.jar com/trolltech/images/*png
        com/trolltech/examples/Application.class -C lib
        libcom_trolltech_qt_core.so -C lib libcom_trolltech_qt_gui.so
        com/trolltech/qt/*class com/trolltech/qt/gui/*class
        com/trolltech/qt/core/*class -C $QTDIR/lib libQtGui.so.4 -C
        $QTDIR/lib libQtCore.so.4 qt_system_libs -C /usr/lib
        libstdc++.so.5 -C lib libqtjambi.so

This example uses a source package. If you have a prebuilt package, the Qt libraries are located in the same directory as Qt Jambi's libraries (i.e., the QTDIR variable would be set to the Qt Jambi directory in the example above).

The Application Example only uses the `com.trolltech.core` and `com.trolltech.gui` packages, so we only need to include libraries for these. If you import other packages, you also need to include the native libraries for these. Note that we also do not need to include any plugins.

With the created JAR bundle, it is possible to run the Application example on systems that do not have Qt or Qt Jambi installed (a Java installation must be present, of course):

            java -jar application.jar

### Creating a .jar file for MSVC 2005

Since the deployment of MSVC 2005 applications is somewhat involved, we here show the contents of a `.jar` file. This is not the complete contents of the file, but shows the MSVC relevant contents.

          QtCore4.dll
          QtGui4.dll
          qtjambi.dll
          com_trolltech_qt_core.dll
          com_trolltech_qt_gui.dll
          msvcr80.dll
          msvcp80.dll
          msvcm80.dll
          Microsoft.VC80.CRT.manifest
          plugins/imageformats/qjpeg4.dll
          plugins/imageformats/Microsoft.VC80.CRT/msvcr80.dll
          plugins/imageformats/Microsoft.VC80.CRT/msvcp80.dll
          plugins/imageformats/Microsoft.VC80.CRT/msvcm80.dll
          plugins/imageformats/Microsoft.VC80.CRT/Microsoft.VC80.CRT.manifest
          qt_system_libs

          ...

The `qt_system_libs` file must include the `msvc*80.dll` files and the manifest. If an application uses other plugins, they are added in the same manner. See also the Including Plugins section. Other files can be added as described in the previous section.

## Creating a Web Start Application

Java Web Start is a helper application that gets associated with a Web browser. When a user clicks on a link that points to a special launch file, the browser launches Java Web Start, which then automatically downloads, caches, and runs the given Java Technology-based application.

The easiest way to create the launch file is to modify an existing JNLP (Java Network Launching Protocol and API) file to fit your requirements. The application `.jar` file can be created using the approach described in the previous section; bundle all the class files, resources and native libraries into one single `.jar` file.

Note that for cross platform binaries, it might be useful to specify which libraries that should be loaded on a given platform. This can be done using the JNLP file.

The JNLP file is an XML document, and has a `resources` element that is used to specify all the resources, such as Java class files, native libraries, and system properties, that are part of the application. A resource definition can be restricted to a specific operating system, architecture, or locale using the `os`, `arch`, and `locale` attributes. For example:

            <resources os="Windows" arch="x86">
                <j2se version="1.5+"/>
                <jar href="qtjambi-win32.jar" />
            </resources>

For more information about deploying Web Start applications, please see the Java Web Start Developer's Guide