<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- /home/gvatteka/dev/qtjambi/4.3/scripts/../doc/src/qtjambi-deployment.qdoc -->
<head>
<title>Deploying Qt Jambi Applications</title>
<link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<h1 align="center">Deploying Qt Jambi Applications<br /><small></small></h1>
<p>Java provides a number of different features which makes it easier to deploy applications, such as the Web Start technology, Java Archives (<tt>.jar</tt> files) and, of course, the virtual machine that enables you to compile your application to bytecode once and run on all architectures.</p>
<p>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.</p>
<p>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.</p>
<p>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 <tt>.jar</tt> 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".</p>
<ul><li><a href="#resolving-native-libraries">Resolving Native Libraries</a></li>
<li><a href="#including-resources">Including Resources</a></li>
<li><a href="#including-plugins">Including Plugins</a></li>
<li><a href="#creating-an-executable-jar-file">Creating an Executable .jar File</a></li>
<li><a href="#creating-a-web-start-application">Creating a Web Start Application</a></li>
</ul>
<a name="resolving-native-libraries"></a>
<h2>Resolving Native Libraries</h2>
<p>The Qt Jambi native libraries are located in the <tt>lib</tt> directory in the Qt Jambi directory. If you have a prebuildt 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 <tt>lib</tt> directory in the Qt directory.</p>
<p>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.</p>
<p>The Qt and Qt Jambi native libreries 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 <tt>qt_system_libs</tt>, which should be located somewhere in the classpath root. One can also specify the libraries on the command line with the <tt>com.trolltech.qt.systemlibraries</tt> variable, which should contain paths to the libraries. The libraries are loaded in the order listed in the file or on the command line.</p>
<p>We present a table with the necessary libraries below:</p>
<p><table width="75%" align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th>Platform</th><th>Native Libraries</th></tr></thead>
<tr valign="top" class="odd"><td>MSVC 6.0</td><td>msvcp60.dll and msvcr60.dll</td></tr>
<tr valign="top" class="even"><td>MSVC 2002</td><td>msvcr70.dll and msvcp70.dll</td></tr>
<tr valign="top" class="odd"><td>MSVC 2003</td><td>msvcr71.dll and msvcp71.dll</td></tr>
<tr valign="top" class="even"><td>MSVC 2005</td><td>msvcr80.dll and msvcp80.dll</td></tr>
<tr valign="top" class="odd"><td>Open Source Windows Version</td><td>mingwm10.dll</td></tr>
<tr valign="top" class="even"><td>Linux</td><td>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 <tt>ldd</tt> utility.</td></tr>
<tr valign="top" class="odd"><td>Mac OS X</td><td>No libraries are required on Mac OS X.</td></tr>
</table></p>
<p>There are also tools on each platform for checking library dependencies. UNIX systems has the <tt>ldd</tt> utility, Mac OS X provides <tt>oTool</tt>. Windows has no standard tool, but a good freely available application is the <a href="http://www.dependencywalker.com/">Dependency Walker</tt></a>. MSVC includes its own application: <tt>depends</tt>.</p>
<p>If you still have problems, you can set the <tt>com.trolltech.qt.verbose-loading</tt> system property, in which case Qt Jambi will report which libraries are missing.</p>
<p><b>The Qt Jambi Generator and Custom Libraries</b></p>
<p>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 <i>and</i> C++, both as executable <tt>.jar</tt> files and using the Web Start technology.</p>
<p>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 The QJ Generator</tt> documentation.</p>
<a name="including-resources"></a>
<h2>Including Resources</h2>
<p>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 <tt>java.io.File</tt> class), Qt Jambi allows resources to be used wherever a file name is expected. Resources are identified by a <tt>classpath</tt>: prefix.</p>
<p align="center"><img src="images/accessing-resources.png" /></p><p>Note that it is also possible to load resources as raw data:</p>
<pre> QFile file = new QFile("classpath:images/fileopen.png");
file.open(QFile.OpenMode.ReadOnly);
QByteArray rawData = file.readAll();</pre>
<p>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.</p>
<a name="including-plugins"></a>
<h2>Including Plugins</h2>
<p>In addition to the Qt native libraries, you need to deploy Qt plugins, such as JPEG support and SQL drivers. See the <a href="plugins-howto.html">plugins document</tt></a> for more information about Qt plugins.</p>
<p>The Qt plugins are located in the <tt>plugins</tt> directory in the directory where Qt Jambi is installed. They are placed in subdirectories according to type, e.g., SQL drivers and image formats.</p>
<p>Plugins are deployed in a <tt>.jar</tt> file following the same directory structure as in the Jambi installation directory. When running the application, the <tt>com.trolltech.qt.pluginjars</tt> system property must be set to contain the path to the <tt>.jar</tt> file containing the plugins. The plugins does not need to have their own file, so it is, for instance, possible to deploy them in the same file as your application.</p>
<a name="creating-an-executable-jar-file"></a>
<h2>Creating an Executable .jar File</h2>
<p>To deploy Qt Jambi applications using the executable <tt>.jar</tt> file approach is straight forward:</p>
<pre> jar mcf <manifest file> myApplication.jar <my class files>
<my resources> <native libraries> <plugins></pre>
<p>Simply put all resources, native libraries, plugins ,and application <tt>.class</tt> files into one single <tt>.jar</tt> 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.</p>
<p>For instance, if you were to create a file for the <a href="qtjambi-application.html">Application Example</tt></a>, the manifest file will look like this:</p>
<pre> Main-Class: com.trolltech.examples.Application</pre>
<p>The qt_system_libs file on Linux will read:</p>
<pre> libstdc++.so.6</pre>
<p>The necessary system libraries on other platforms are given in <a href="qtjambi-deployment.html#resolving-native-libraries">Resolving Native Libraries</tt></a>.</p>
<p>Assuming your current directory is the Jambi directory, you can create a <tt>.jar</tt> file on a Linux system using debug libraries with:</p>
<pre> jar mcf Manifest.text application.jar com/trolltech/images/*png com/trolltech/examples/Application.class
-C lib libcom_trolltech_qt_core_debuglib.so -C lib libcom_trolltech_qt_gui_debuglib.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.6 -C lib libqtjambi_debuglib.so</pre>
<p>The Application Example only uses the <tt>com.trolltech.core</tt> and <tt>com.trolltech.gui</tt> 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.</p>
<p>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):</p>
<pre> java -Dcom.trolltech.qt.debug -jar application.jar</pre>
<a name="creating-a-web-start-application"></a>
<h2>Creating a Web Start Application</h2>
<p>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.</p>
<p>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 <tt>.jar</tt> file can be created using the approach described in the previous section; bundle all the class files, resources and native libraries into one single <tt>.jar</tt> file.</p>
<p>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.</p>
<p>The JNLP file is an XML document, and has a <tt>resources</tt> 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 <tt>os</tt>, <tt>arch</tt>, and <tt>locale</tt> attributes. For example:</p>
<pre> <resources os="Windows" arch="x86">
<j2se version="1.5+"/>
<jar href="qtjambi-win32.jar" />
</resources></pre>
<p>For more information about deploying Web Start applications, please see the <a href="http://java.sun.com/j2se/1.5.0/docs/guide/javaws/developersguide/contents.html">Java Web Start Developer's Guide</tt></a></p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%">Copyright © 2007 <a href="trolltech.html">Trolltech</a></td>
<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt Jambi </div></td>
</tr></table></div></address></body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a6711891ce757817bba854bf3f25205a
>
files
>
2353
