path: root/doc/src/installation.qdoc

/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page installation.html

\title Installation Guide
\tableofcontents

\section1 Get the QtMobility API Package
You can get the most recent distribution package, which is now part of the Qt SDK, from
\l {http://get.qt.nokia.com}. You can also get the Mobility source code from
\l {http://qt.nokia.com/products/qt-addons/mobility/}.

\section1 Pre-requisites & Dependencies
To install QtMobility you must already have installed
Qt 4.6 or higher, visit \l {http://get.qt.nokia.com} to obtain
a copy. However, QtMobility's QML components are not enabled unless Qt 4.7 or higher is used.
Furthermore perl must be installed and available in the environment path.
Windows environments may require the installation of a perl interpreter such as
\l {http://www.activestate.com/activeperl} {ActivePerl}. On the Maemo 5 (Fremantle)
platform PR1.2 firmware release or newer is required, and the Qt 4.7 packages
are required.


QtMobility Project APIs are comprised of a number of domains. Some of
these domains have dependencies and these are outlined below:

\table 80%
\header
    \o API
    \o Dependency
\row
    \o Bearer Management
    \o The Linux backend depends on QtDBus (auto-detected) and \l {http://projects.gnome.org/NetworkManager/} {NetworkManager},
       although Bearer Management will compile without them there will be reduced functionality.

       On Mac, QtBearer depends on CoreWLAN (auto-detected) if Mac OS X SDK 10.6 is available. Functionality will be reduced if CoreWLAN is not available.
\row
    \o Contacts
    \o The Maemo 5 backend depends on \l {http://maemo.org/packages/view/libosso-abook/}{libosso-abook}.
\row
    \o Document Gallery
    \o The Maemo 5 backend depends on QtDBus and \l {http://project.gnome.org/Tracker}{Tracker}.
\row
    \o Location
    \o The Symbian backend uses the LBT (Location Based Triggering) library for area notifications.
       Area notifications will be disabled at compile time if the LBT library is not found.

       The LBT library is not publicly available at the time of writing.
       The developer documentation for \l {http://carbidehelp.nokia.com/help/index.jsp?topic=/S60_5th_Edition_Cpp_Developers_Library/GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6/html/Location_ServicesIndexPage.html}
       {S60 Location Services} is probably the best source for LBT availability updates, as it
       will be updated when the library is released.

       The landmarks backend for *nix,Windows and Fremantle platforms depends on QtSql. QtSql also needs the SQLite 3 driver (enabled by default in qt) at runtime.

       The landmarks backend on the Harmattan and Meego platforms depends on QtSparql and QtSparql Tracker Extensions.  There is also a runtime dependency
       for \l {http://project.gnome.org/Tracker}{Tracker} 0.9.35 or greater, and on libqtsparql-tracker which is the Tracker driver for QtSparql.
\row
    \o Messaging
    \o On Linux, QtMessaging depends on qtopiamail from \l {http://labs.trolltech.com/blogs/category/qtmessaging}{QMF}.

       The Windows Mobile backend depends on ActiveSync version 4.5.

       While not supported for this release the desktop Windows backend
       requires that a MAPI subsystem is installed. Note that messaging
       functionality will not work if you are using the MinGW compiler.
       Additionally note that CE MAPI is available on Windows Mobile and
       does not need to be installed separately.

       For more detailed instructions on installation on Windows Mobile
       see \l {Messaging Installation On Windows Mobile}

       The messaging API SMS/MMS functionality requires that the platform
       provides SMS/MMS facilities. Email functionality requires that an email
       account is available on the platform.
\row
    \o Multimedia
    \o On all platforms, QtMultimediaKit depends on QtGui and QtNetwork.

       On all platforms, QML elements for sound effects and music and video playing are exported if QtDeclarative (auto-detected) is available.

       On all platforms, additional rendering paths are enabled of QtOpenGL (auto-detected) is available.
    \o
    \o
\row
    \o Multimedia mediaservice plugins
    \o The audioengine plugin for Unix depends on QtMultimediaKit.

       The dsengine plugin for desktop Windows depends on QtMultimediaKit.

       The gstengine plugin for Linux and Maemo depends on gstreamer-0.10 (>= 0.10.19), gstreamer-audio-0.10 (>= 0.10.19), gstreamer-base-0.10 (>= 0.10.19), gstreamer-interfaces-0.10 (>= 0.10.19) and gstreamer-video-0.10 (>= 0.10.19).
       If asound (auto-detected) is available, ALSA device detection will be enabled.

       To enable all mediaservices on Symbian one must download sdk plugins. Sdk plugins are available at \l http://wiki.forum.nokia.com/index.php/SDK_API_Plug-in
       For 5th edition sdk plugins are installed with installer (all at once), but for FP1 and FP2 devices a zip is provided. You will need following plugins to compile all features:
       AudioRoutingAPI, Tuner Utility,  (only for 3rd FP1), Radio Utility API (for 3rd FP2 and 5th ed), SymbianOnboardCameraAdvancedSettings API (for 3rd FP2 and 5th ed),
       MDF DevVideoRecord API (for 3rd FP2 and 5th ed).
       For camera autofocus support in 3rd edition FP1 one must download the following camera example app at
       \l http://www.forum.nokia.com/info/sw.nokia.com/id/2f492479-ac8c-4c3e-aa90-cc883e190d83/S60_Platform_Camera_Example_with_AutoFocus_Support_v2_2_en.zip.html
       and extract the autofocus extension plugin that is contained within it, namely  autofocus_extension_library_s60_3rd_ed.zip.

       Multimedia also includes audio and video (from 1.0.1 onwards) and in Symbian we need MMFDevSound API-SDK plugin to compile/link API. This is also available in Forum Nokia as a supplementary pack.

\row
    \o Publish & Subscribe
    \o On Linux, QtPublishSubscribe depends on QtNetwork.

\row
    \o  Sensors
    \o  The QtSensors s60_sensor_api plugin for S60 3.1 depends on the \l {http://www.forum.nokia.com/info/sw.nokia.com/id/4284ae69-d37a-4319-bdf0-d4acdab39700/Sensor_plugin_S60_3rd_ed.html}{Sensor API Plug-in}
\row
    \o
    \o  The QtSensors symbian plugin for S60 3.2 depends on the backported \l {http://www.forum.nokia.com/info/sw.nokia.com/id/8059e8ae-8c22-4684-be6b-d40d443d7efc/Sensor_API_Plug_in_S60_3rd_FP2.html}{Sensor API Plug-in}
\row
    \o  Service Framework
    \o  On all platforms, QtServiceFramework depends on QtSql. QtSql also needs the SQLite 3 driver (enabled by default) at runtime.
\row
    \o System Information
    \o On all platforms, QtSystemInfo depends on QtNetwork.

       Linux backend depends on QtDBus (auto-detected), HAL and \l {http://projects.gnome.org/NetworkManager/} {NetworkManager},
       although System Information will compile without them, there will be reduced functionality. It also depends on QtGui, and
       on libbluetooth development headers.
       As well, for Linux machines that have libblkid installed, this will be used as a last resort for discovering UUID of storage.

       The Mac backend depends on CoreWLAN (auto-detected) if the Mac OS X 10.6 SDK is available. It will compile
       with older SSDKsbut there will be reduced functionality.

       For Maemo depends on QtDBus (auto-detected). QtDBus is used to communicate with HAL, and functionality will be reduced if either is unavailable.

       The Symbian backend depends on WLANManagementAPI. WLANManagementAPI plugin is available at \l http://wiki.forum.nokia.com/index.php/SDK_API_Plug-in
       For 5th edition sdk plugins are installed with installer (all at once), but for FP1 and FP2 devices a WLANManagementAPI.zip is provided.

       Also for Symbian, it depends on SIM Utils API SDK plugin available from Forum Nokia \l http://wiki.forum.nokia.com/index.php/File:SIMUtilsAPI_3x_50.zip

       On Symbian 3 FP2, it depends on the Multiple Drive Support available from Forum Nokia http://www.forum.nokia.com/Library/Tools_and_downloads/Other/Multiple_Drive_Support_plug-in.xhtml
\row
    \o QtVersit
    \o On all platforms, QtVersit depends on QtContacts and QtOrganizer.
\endtable

\section1 Unpacking
Unpack the QtMobility archive if you have not done so already,
on Unix (X11 and Mac):
\code
        cd /tmp
        gunzip %DISTNAME%.tar.gz        #uncompress the archive
        tar xvf %DISTNAME%.tar          #unpack it
\endcode

This creates the directory \c {/tmp/%DISTNAME%} containing the files
from the archive.  We only support the GNU version of the tar
archiving utility.  Note on some systems it is called gtar.

On windows, uncompress the zip file into the directory you want
QtMobility Project installed, extracting to \c {C:\QtMobility}
will create the directory \c {C:\QtMobility\%DISTNAME%}

NOTE: The install path(prefix) must not contain any spaces.

\section1 Building
Ensure that all compile time dependencies for your particular
platform have been met before building.

If Qt is installed for multiple platforms it is also important
to ensure that the correct version of \c{qmake} is being used.

\bold{Note:} Static builds of Qt are not supported by QtMobility.

\section2 Building On Unix

To configure the QtMobility libraries for your machine, run the
\c./configure script in the package directory.

To specify the installation directory you may use the -prefix
option.  Not passing a prefix installs the
mobility libraries into $PWD/install.

\code
    cd /tmp/%DISTNAME%
    ./configure -prefix $TARGET_DIR
\endcode

    Type \c {./configure -help} to get a list of all available options.
    If you are building for maemo you need to use the -maemo option
    with configure.

    To create all the libraries and tools, type:
\code
    make
\endcode

    To install the libraries and tools to $TARGET_DIR, type:
\code
    make install
\endcode

    If you have specified an install directory with root ownership,
    you will need to type:
\code
    su -c "make install"
        or
    sudo make install
\endcode

    and enter in the appropriate password.

    Note that on some systems the make utility is named differently,
    e.g. gmake.  The configure script tells you which make utility to
    use.

\section2 Building On Windows
    To configure the QtMobility libraries for your machine, run
    configure in the package directory.

    To specify the installation directory you may use the -prefix
    option.  Not passing a prefix installs the mobility
    libraries into an install directory within the current working
    directory.

    \code
        cd c:\QtMobility\%DISTNAME%
        configure -prefix %TARGET_DIR%
    \endcode

    Type \c {configure -help} to get a list of all available options.

    The actual commands needed to build and install QtMobility depends on your
    development system.  To create and install the  libraries and tools from a
    Microsoft Visual Studio command prompt, type:
\code
    nmake
    nmake install
\endcode

\section2 Building For Windows CE

    The process is much the same as for Windows, although it is
    important to run the \c{setcepaths} script from the \c{bin}
    directory of the Qt for Windows CE installation to ensure that
    the correct headers and libraries are used.

\section2 Building For Symbian On Windows
    Building QtMobility for Symbian is not necessary as the
    package contains pre-built binaries for the SDK and
    SIS file for the device.  See the \c {INSTALL.symbian}
    file on how to deploy these. The file is located in the root directory
    of the package.

    If you wish to build QtMobility yourself,
    run configure in the package directory. (-prefix
    cannot be used since the libraries are installed
    into the SDK directory)

    \code
        cd c:\QtMobility\%DISTNAME%
        configure
    \endcode

    Type \c {configure -help} to get a list of all available options.

    To create and deploy the libraries and tools
    for the emulator run:
\code
    make debug-winscw
\endcode

    To create the libraries and tools using the commercial compiler RVCT
    for a device, run:
\code
    make release-armv5
\endcode

    Note: \c {make install} has no meaning for building
    on Symbian.
    The libraries will be deployed into the SDK (when running make) and will
    be ready to use for compiling applications for the
    emulator and/or device.

\section2 Building For Mac OS X
    The process is the same as for Unix, with the additional configuration
    option of \c { -sdk /Developer/SDKs/MacOSX10.5.sdk } to specify an Apple SDK
    version other than the default.

    Note: QtMobility currently has no support for building with Xcode.

    Note: QtMobility will be built using the same frameworks configuration option
    that Qt was built with.

\section2 Building Individual QtMobility Modules

    QtMobility is comprised of several modules but all of
    these may not need to be built.  To specify which modules
    should be built, use the \c{-modules} switch with the configure
    script when performing the configure step as outlined above.

    e.g. To build just the bearer module:
\code
    configure -modules bearer
\endcode

    If multiple modules are required the module names should be separated
    by a space and surrounded by double quotation marks. If a selected module
    depends on other modules the dependencies will be enabled automatically.

    .e.g. To build just the bearer and location modules:
\code
    configure -modules "bearer location"
\endcode

    Type \c {configure -help} to see the names of the available modules.

\section1 Making the libraries available to applications

In order to use QtMobility some environment variables
need to be extended to locate the libraries, which are
placed in the lib directory of the install path.

\section2 Making the libraries available on Unix
The environment variable LD_LIBRARY_PATH should be extended to include:
\c {$TARGET_DIR/lib}

In .profile (if your Unix shell is bash,ksh,zsh or sh),
add the following lines
\code
    LD_LIBRARY_PATH=$TARGET_DIR/lib:$LD_LIBRARY_PATH
    export LD_LIBRARY_PATH
\endcode

In .login (incase your shell is csh or tcsh), add the following
line:
\code
    setenv LD_LIBRARY_PATH=$TARGET_DIR/lib:$LD_LIBRARY_PATH
\endcode

If you use a different Unix shell, please modify your
your environment variables accordingly.

\section2 Making the libraries available on Windows
The environment variable PATH should be extended to include:
\c {C:\%TARGET_DIR%\lib}

For newer versions of windows, PATH can be extended
through "Start->Settings->Control Panel->System->Advanced->
Environment variables" and for older versions by
editing \c{C:\autoexec.bat}

\section2 Making the libraries available on Windows CE

Environment variables do not exist on Windows CE, and so users
of QtMobility for Windows CE have to do things slightly differently.
A pre-requisite for QtMobility applications is that the Qt libraries and plugins have been deployed as per Qt's documentation.

The deployment of the libraries to the device is normally done
with Microsoft Visual Studio or Microsoft ActiveSync.

The libraries can be made globally available by deploying them
to \c{C:\Windows} on the device, or can be deployed once per
application by copying them into the same directory as the executable. QtMobility
expects plug-ins in the subdirecty \c {plugins/<APIname>} in one of
the locations specified by \l QCoreApplication::libraryPaths() which includes
\c{C:\Windows} and the Mobility application's directory.

And now the installation is complete, we hope you enjoy
using QtMobility.
*/