INSTALL.TXT

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 linker.


2. Plugins

    For Qt Solutions plugins (e.g. image formats), both debug and
    release versions of the plugin are built by default when
    appropriate, since in some cases the release Qt library will not
    load a debug plugin, and vice versa. The plugins are automatically
    copied into the plugins directory of your Qt installation when
    built, so no further setup is required.

    Plugins may also be built statically, i.e. as a library that will be
    linked into your application executable, and so will not need to
    be redistributed as a separate plugin DLL to end users. Static
    building is required if Qt itself is built statically. To do it,
    just add "static" to the CONFIG variable in the plugin/plugin.pro
    file before building. Refer to the "Static Plugins" section in the
    chapter "How to Create Qt Plugins" for explanation of how to use a
    static plugin in your application. The source code of the example
    program(s) will also typically contain the relevant instructions
    as comments.



Uninstalling
------------

    The following command will remove any fils that have been
    automatically placed outside the package directory itself during
    installation and building

	make distclean [or nmake if your are using Microsoft Visual C++]

    If Qt Assistant documentation or Qt Designer plugins have been
    installed, they can be uninstalled manually, ref. above.


Enjoy! :)

- The Qt Solutions Team.