INSTALLATION INSTRUCTIONS
These instructions refer to the package you are installing as
some-package.tar.gz or some-package.zip. The .zip file is intended for use
on Windows.
The directory you choose for the installation will be referred to as
your-install-dir.
Note to Qt Visual Studio Integration users: In the instructions below,
instead of building from command line with nmake, you can use the menu
command 'Qt->Open Solution from .pro file' on the .pro files in the
example and plugin directories, and then build from within Visual
Studio.
Unpacking and installation
--------------------------
1. Unpacking the archive (if you have not done so already).
On Unix and Mac OS X (in a terminal window):
cd your-install-dir
gunzip some-package.tar.gz
tar xvf some-package.tar
This creates the subdirectory some-package containing the files.
On Windows:
Unpack the .zip archive by right-clicking it in explorer and
choosing "Extract All...". If your version of Windows does not
have zip support, you can use the infozip tools available
from www.info-zip.org.
If you are using the infozip tools (in a command prompt window):
cd your-install-dir
unzip some-package.zip
2. Configuring the package.
The configure script is called "configure" on unix/mac and
"configure.bat" on Windows. It should be run from a command line
after cd'ing to the package directory.
You can choose whether you want to use the component by including
its source code directly into your project, or build the component
as a dynamic shared library (DLL) that is loaded into the
application at run-time. The latter may be preferable for
technical or licensing (LGPL) reasons. If you want to build a DLL,
run the configure script with the argument "-library". Also see
the note about usage below.
(Components that are Qt plugins, e.g. styles and image formats,
are by default built as a plugin DLL.)
The configure script will prompt you in some cases for further
information. Answer these questions and carefully read the license text
before accepting the license conditions. The package cannot be used if
you do not accept the license conditions.
3. Building the component and examples (when required).
If a DLL is to be built, or if you would like to build the
examples, next give the commands
qmake
make [or nmake if your are using Microsoft Visual C++]
The example program(s) can be found in the directory called
"examples" or "example".
Components that are Qt plugins, e.g. styles and image formats, are
ready to be used as soon as they are built, so the rest of this
installation instruction can be skipped.
4. Building the Qt Designer plugin (optional).
Some of the widget components are provided with plugins for Qt
Designer. To build and install the plugin, cd into the
some-package/plugin directory and give the commands
qmake
make [or nmake if your are using Microsoft Visual C++]
Restart Qt Designer to make it load the new widget plugin.
Note: If you are using the built-in Qt Designer from the Qt Visual
Studio Integration, you will need to manually copy the plugin DLL
file, i.e. copy
%QTDIR%\plugins\designer\some-component.dll
to the Qt Visual Studio Integration plugin path, typically:
C:\Program Files\Trolltech\Qt VS Integration\plugins
Note: If you for some reason are using a Qt Designer that is built
in debug mode, you will need to build the plugin in debug mode
also. Edit the file plugin.pro in the plugin directory, changing
'release' to 'debug' in the CONFIG line, before running qmake.
Solutions components are intended to be used directly from the package
directory during development, so there is no 'make install' procedure.
Using a component in your project
---------------------------------
To use this component in your project, add the following line to the
project's .pro file (or do the equivalent in your IDE):
include(your-install-dir/some-package/src/some-package.pri)
This adds the package's sources and headers to the SOURCES and HEADERS
project variables respectively (or, if the component has been
configured as a DLL, it adds that library to the LIBS variable), and
updates INCLUDEPATH to contain the package's src
directory. Additionally, the .pri file may include some dependencies
needed by the package.
To include a header file from the package in your sources, you can now
simply use:
#include <SomeClass>
or alternatively, in pre-Qt 4 style:
#include <some-class.h>
Refer to the documentation to see the classes and headers this
components provides.
Install documentation (optional)
--------------------------------
The HTML documentation for the package's classes is located in the
your-install-dir/some-package/doc/html/index.html. You can open this
file and read the documentation with any web browser.
To install the documentation into Qt Assistant (for Qt version 4.4 and
later):
1. In Assistant, open the Edit->Preferences dialog and choose the
Documentation tab. Click the Add... button and select the file
your-install-dir/some-package/doc/html/some-package.qch
For Qt versions prior to 4.4, do instead the following:
1. The directory your-install-dir/some-package/doc/html contains a
file called some-package.dcf. Execute the following commands in a
shell, command prompt or terminal window:
cd your-install-dir/some-package/doc/html/
assistant -addContentFile some-package.dcf
The next time you start Qt Assistant, you can access the package's
documentation.
Removing the documentation from assistant
-----------------------------------------
If you have installed the documentation into Qt Assistant, and want to uninstall it, do as follows, for Qt version 4.4 and later:
1. In Assistant, open the Edit->Preferences dialog and choose the
Documentation tab. In the list of Registered Documentation, select
the item com.nokia.qtsolutions.some-package_version, and click
the Remove button.
For Qt versions prior to 4.4, do instead the following:
1. The directory your-install-dir/some-package/doc/html contains a
file called some-package.dcf. Execute the following commands in a
shell, command prompt or terminal window:
cd your-install-dir/some-package/doc/html/
assistant -removeContentFile some-package.dcf
Using the component as a DLL
----------------------------
1. Normal components
The shared library (DLL) is built and placed in the
some-package/lib directory. It is intended to be used directly
from there during development. When appropriate, both debug and
release versions are built, since the run-time linker will in some
cases refuse to load a debug-built DLL into a release-built
application or vice versa.
The following steps are taken by default to help the dynamic
linker to locate the DLL at run-time (during development):
Unix: The some-package.pri file will add linker instructions to
add the some-package/lib directory to the rpath of the
executable. (When distributing, or if your system does not support
rpath, you can copy the shared library to another place that is
searched by the dynamic linker, e.g. the "lib" directory of your
Qt installation.)
Mac: The full path to the library is hardcoded into the library
itself, from where it is copied into the executable at link time,
and ready by the dynamic linker at run-time. (When distributing,
you will want to edit these hardcoded paths in the same way as for
the Qt DLLs. Refer to the document "Deploying an Application on
Mac OS X" in the Qt Reference Documentation.)
Windows: the .dll file(s) are copied into the "bin" directory of
your Qt installation. The Qt installation will already have set up
that directory to be searched by the dynamic linke