|  | Home · Examples

# Installing Qt Jambi

Qt Jambi is available both in prebuilt and source packages for Linux, Mac OS X, and Windows. Java 1.5 or later is required to install Qt Jambi.

The procedure of installing is different depending on whether you have downloaded a source or prebuilt package. This installation guide has separate sections for each approach.

Enjoy !

- Installing from a Prebuilt Package

- Manually Launching Qt Jambi Applications

- Alternate way of loading native libraries

- Building Qt Jambi from a Source Package

- Configuring the System for Qt Jambi
- Building Qt for Qt Jambi
- Setting up the environment
- Building Qt Jambi
- Trouble Shooting

- Common Problems
- Load Issues

- Platform Notes
- Running the Qt Designer
- Running the Qt Jambi Generator

## Installing from a Prebuilt Package

After extracting the package, you are ready to run the Launcher, which is an application that runs the examples and demos that come with Qt Jambi.

To run the examples and demo launcher on Windows run:

    qtjambi.exe

On Linux and Mac OS X run:

    qtjambi.sh

Running these files will verify the virtual machine version and set the correct environment for running Qt Jambi applications.

When you are ready to distribute your own applications, see the deployment document.

### Manually Launching Qt Jambi Applications

To manually launch applications, you need to include the following `.jar` files in your classpath:

- `qtjambi-4.4.0_01.jar`, which contains the Jambi classes.
- The platform archive, which contains the native libraries used by Qt Jambi. The archive is named after the operating system and compiler used to build the libraries; for instance, `qtjambi-win32-msvc2005-4.4.0_01.jar` for Windows and MSVC 2005.
- To run the examples or launcher, the classpath must also include the `qtjambi-examples-4.4.0_01.jar`.

All three files live in the in the Qt Jambi installation directory. We give an example for each operating system bellow:

    // Linux
    java -cp qtjambi-4.4.0_01.jar:qtjambi-linux32-gcc-4.4.0_01.jar:qtjambi-examples-4.4.0_01.jar com.trolltech.launcher.Launcher

    // Mac OS X
    java -XstartOnFirstThread -cp qtjambi-4.4.0_01.jar:qtjambi-macosx-gcc-4.4.0_01.jar:qtjambi-examples-4.4.0_01.jar com.trolltech.launcher.Launcher

    // Windows
    java -cp qtjambi-4.4.0_01.jar;qtjambi-win32-msvc2005-4.4.0_01.jar;qtjambi-examples-4.4.0_01.jar com.trolltech.launcher.Launcher

Note: When running a Qt Jambi application on Mac, it is necessary to pass the `-XstartOnFirstThread` argument to the Java executable.

#### Alternate way of loading native libraries

As described in the previous section, Jambi loads the native libraries from the platform archive (when it is included in the classpath).

An alternative way of loading the native libraries is to rely on Java's standard method of loading native libraries. This is done by specifying either the JVM system property `-Djava.library.path=[path_to_libraries]` or including the paths in the following environment variable:

Platform | Comment
--- | ---
Windows | Set the `PATH` environment variable to include the bin directory in the Qt Jambi directory.
Linux | Set the `LD_LIBRARY_PATH` environment variable to include the lib directory in the Qt Jambi directory.
Mac OS X | Set the `DYLD_LIBRARY_PATH` environment variable to include the lib directory in the Qt Jambi directory.

Note that the path to the Jambi libraries should be the first path in these variables. If not, Jambi might find other and likely incompatible versions of the libraries. On Linux, for instance, the library libQtCore.4.so in /usr/lib is by default part of LD_LIBRARY_PATH.

Some of Qt's functionality is loaded via native plugins. This includes for instance support for JPEG images. The plugins are located in the `plugins` directory in the Qt Jambi installation directory.

Qt Jambi searches for the plugins from the directories in the QT_PLUGIN_PATH environment variable (when the platform archive is not used). So you should set QT_PLUGIN_PATH to the `plugins` directory.

You are then ready to run Qt Jambi applications. An example of how to run the launcher manually is illustrated below:

    java -cp qtjambi-4.4.0_01.jar:qtjambi-examples-4.4.0_01.jar com.trolltech.launcher.Launcher

## Building Qt Jambi from a Source Package

This section describes how to build Qt Jambi from source. We first explain how to configure your system, and then we go through the procedure of building Qt Jambi from the command line. Finally, we look at some common installation problems.

Note that a Qt Jambi source package also requires a Qt source package. To avoid potential binary incompatibilities, it is highly recommended that you rebuild Qt before building Qt Jambi. On Mac OS X, Qt must be configured without frameworks (by running the `configure` script with the --no-framework option).

### Configuring the System for Qt Jambi

In addition to the Qt source package, you will need JDK 1.5 or higher and the build utility `ant`.

### Building Qt for Qt Jambi

The first step is to build Qt for Qt Jambi. A normal Qt build will normally work, but there are a few exceptions. For more details on building Qt on any given system see the Qt installation guides.

Configuration | Comment
--- | ---
All | Some features in Qt are turned on or off for Qt Jambi by configuring with `-D QT_JAMBI_BUILD`. Qt Jambi also has no need for the Qt 3 support library so it is recommended to compile with `-no-qt3support`.
Mac OS X | Qt Jambi only supports Qt configured with `-no-framework` and because of compatibility it is recommended to configure Qt against the 10.4 SDK, `-sdk /Developer/SDKs/MacOSX10.4u.sdk`
Linux | Sun's Java Virtual Machine has a bug preventing it from using MMX and SSE instructions. For deployment against 1.5 Java runtimes, configure Qt with the options `-no-mmx -no-sse -no-sse2 -no-3dnow` to avoid problems. In addition, because Qt Jambi requires both the Qt headers and the libraries to be located relative to QTDIR, Qt should be configured with `-prefix $PWD`, hence not installed.
Windows (MSVC 2005 or newer) | `-plugin-manifests` is required for plugins to load properly.

### Setting up the environment

The following table describes the environment variables necessary to install Qt Jambi.

QTDIR | This variable must contain the path to the directory where Qt is installed.
JAVA_HOME | This variable must contain the path to the directory where Java is installed.

### Building Qt Jambi

Qt Jambi provides an ant task which handles all the tasks of building the Qt Jambi libraries. To build Qt Jambi from scratch, run ant without arguments in the Jambi installation directory.

    > ant

in the Qt Jambi directory. Please note that Qt Jambi requires the `ant-trax` module of `ant` which is optional in some linux distributions. Running `ant` will automatically go through the following = steps:

- Compile the Qt Jambi Generator
- Generate the Qt Jambi libraries based on the Qt specified by $QTDIR
- Compile the Juic tool
- Compile the and bundle the native libraries
- Compile and bundle the class libraries
- Run Juic over the examples.
- Compile and bundle the examples

For a description of the various sub-targets of the ant build one can:

    > ant -projecthelp

For a description of the various build configurations, one can do:

    > ant help

### Trouble Shooting

If you have trouble compiling and running Qt Jambi, we present problems that are commonly encountered in a table. This should be sufficient to solve most problems; failing that, try asking someone. The Jambi FAQ is a good place to start. In the Jambi Mailing List, active Jambi users and the Jambi development team can be helpful with installation problems; please run Qt Jambi with the `com.trolltech.qt.verbose-loading` system property and give stack traces if Qt Jambi fails to load native libraries.

#### Common Problems

In this section, we have tried to gather common problems encountered while building Qt Jambi. They are listed in a table with columns for the problem description and solution.

Problem | Solution
--- | ---
On Linux the `gcj` (GNU Java Compiler) is located in `/usr/bin`; the path to the correct java version must be before this in the PATH. This usually results in `java.lang.ClassFormatError` errors. | Make sure that it is the correct java executable in the PATH.
Environment variables are not set correctly. | Check with the Configuring the System for Qt Jambi section that your system is properly configured for Jambi.
Qt Jambi uses the Qt Header files to generate the mapping from c++ to java. Unless Qt was built with default settings, you may get link problems for bindings that are not in the native libraries. | Build Qt with default settings
`juic` does not update .jui files that are not modified, which can be a problem if Java sources are deleted. | Run juic with the `-a` option.
Qt Jambi expects that Qt was built with debugging turned off. If Qt was built with debugging, the libraries will not be found. | Run Qt Jambi with the `com.trolltech.qt.debug` system property.
Qt Jambi tries to use the wrong compiler | This can happen on Windows systems with both the MSVC and MinGW compilers installed.You can set the QMAKESPEC variable. Please see the qmake documentation for details.

#### Load Issues

If Jambi cannot find the native libraries, you will get `java.lang.UnsatisfiedLinkError`'s or other load issues. We list search paths below. They are listed in the order Jambi searches for libraries.

- The com.trolltech.qt.library-path system property.
- The classpath (including jar files).
- The subdirectory `lib` (Mac OS X and Linux) or `bin` (Windows) under the root of the Jambi package structure (i.e., the Qt Jambi installation directory).
- The java.library.path system property, which is set to LD_LIBRARY_PATH on Linux, PATH on Windows, and DYLD_LIBRARY_PATH on Mac OS X.

## Platform Notes

We will now take a quick look at platform specific issues.

Platform | Comment
--- | ---
Mac OS X | When running a Qt Jambi application, it is necessary to pass the `-XstartOnFirstThread` argument to the Java executable. Also, if you have a source package, you have to build Qt with the --no-framework option.
Linux / 64 bit: | Install a 32 bit virtual machine, e.g., on Ubuntu, install the `ia32-sun-java5-bin` package and put `/usr/lib/jvm/ia32-java-1.5.0-sun-1.5.0.06/jre/bin` into the `PATH` environment variable.

## Running the Qt Designer

The Qt Designer is Trolltech's tool for designing and building user interfaces. If you have a prebuilt package, you can run it from the command line with the `designer.bat` or `designer.sh` scripts. The Eclipse integration handles the designer automatically.

You will find more information in the Qt Designer document.

## Running the Qt Jambi Generator

The generator is a Qt application which can be used to map C++ based Qt APIs onto equivalent Java APIs. The Qt Jambi package provides an example on how to use the Qt Jambi Generator, located in the `path/to/Qt Jambi/generator_example` directory.

To build the generator example from the source package simply do:

    ant -f build_generator_example.xml

Warning: The Qt Jambi generator is written to handle Qt based source code, and is not intended for mapping C++ libraries in general.