BlackBerry: Added platform specific documentation

Moved some documentation from http://qt-project.org/wiki into qtdocs.

Change-Id: I42588f090ecce49d77bfc31de189d69e554786da
Reviewed-by: Sergio Ahumada <sahumada@blackberry.com>
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

4 files changed, 652 insertions, 1 deletions

diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc
index 1e031045..95fb24a2 100644
--- a/doc/src/external-resources.qdoc
+++ b/doc/src/external-resources.qdoc
@@ -149,3 +149,26 @@
     \externalpage http://qt-project.org/wiki/Qt5ForAndroidBuilding
     \title Building Qt 5 for Android
 */
+/*!
+    \externalpage http://qt-project.org/wiki/Qt5-on-BlackBerry-supported-modules
+    \title BlackBerry supported modules
+*/
+/*!
+    \externalpage http://qt-project.org/wiki/Qt-Creator-with-BlackBerry-10
+    \title Using Qt Creator for BlackBerry 10 Development
+*/
+/*!
+    \externalpage https://developer.blackberry.com/native/documentation/cascades/device_platform/data_access/file_system.html
+    \title Working with the file system
+*/
+
+/*!
+    \externalpage https://developer.blackberry.com/native/documentation/cascades/dev/bb10_devices/
+    \title BlackBerry 10 device characteristics
+*/
+
+/*!
+    \externalpage https://developer.blackberry.com/native/documentation/core/com.qnx.doc.native_sdk.devguide/topic/c_appfund_applifecycle.html
+    \title BlackBerry 10 application lifecycle
+*/
+
diff --git a/doc/src/platforms/blackberry.qdoc b/doc/src/platforms/blackberry.qdoc
new file mode 100644
index 00000000..ad562904
--- /dev/null
+++ b/doc/src/platforms/blackberry.qdoc
@@ -0,0 +1,514 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 BlackBerry Limited. All rights reserved.
+** 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 blackberry_support.html
+    \title Qt for BlackBerry 10
+    \brief Provides information about BlackBerry support in Qt.
+
+    Qt for BlackBerry allows to run Qt 5 applications on devices with BlackBerry
+    10 or later. BlackBerry 10 uses QNX as base OS, so Qt on BlackBerry 10 and Qt
+    on QNX share the same code base.
+
+    Development of Qt applications for the BlackBerry 10 platform is possible using
+    the BlackBerry Native Development Kit. It contains the Momentics IDE along with
+    a cross compiler toolchain and packaging and deployment tools.
+    After setup you can opt for development with Qt Creator, command line tools or the
+    Momentics IDE.
+
+    The following topics provide more details about how to use Qt for BlackBerry:
+    \list
+     \li \l{Getting Started with Qt for BlackBerry 10}{Getting Started}
+     \li \l{Qt 5 on BlackBerry 10}
+     \li \l{Building Qt 5 for BlackBerry 10}
+     \li \l{Deployment on BlackBerry 10}
+     \li \l{Platform and Compiler Notes - BlackBerry}{Platform Notes}
+    \endlist
+*/
+
+/*!
+    \page blackberrygs.html
+    \title Getting Started with Qt for BlackBerry 10
+    \brief Provides instructions to install and configure your development environment.
+
+    \section1 Development with Qt for BlackBerry 10
+    Development of Qt applications for the BlackBerry 10 platform is possible using the
+    \l{https://developer.blackberry.com/native/}{BlackBerry Native Development Kit}.
+    First versions of NDK contained both, the Momentics IDE as well as the NDK itself.
+    In recent releases, developers have to download the
+    \l{https://developer.blackberry.com/native/downloads/}{Momentics IDE}
+    first, which then installs the NDK and simulator packages. Every NDK package includes
+    a cross compiler toolchain, plus packaging and deployment tools, basically all you
+    need for development.
+
+    \section1 Initial Preparation
+    \section2 Get a BlackBerry ID
+
+    The BlackBerry ID is used as an identity reference and is necessary to register as a
+    developer and use the device in developer mode. You can
+    \l{https://blackberryid.blackberry.com}{create a BlackBerry ID online}.
+    If you already use a BlackBerry device, you should have a BlackBerry ID, as well. It is
+    the same ID used in BBM or to download apps from BlackBerry World. If you have such
+    an ID you can use it to get a BlackBerry ID token for development.
+
+    \section2 Get the Momentics IDE
+
+    First
+    \l{https://developer.blackberry.com/native/downloads/}{download the Momentics IDE},
+    set it up and download an NDK with appropriate API level, see this
+    \l{https://developer.blackberry.com/native/documentation/cascades/getting_started/setting_up.html}
+      {article}
+    for more details.
+
+    \section1 Setup
+
+    \section2 Enable the Development Mode on the Device
+    Make sure your device is connected to your computer.
+    Switch on \b{Development Mode} in \e{Settings -> Security and Privacy ->
+    Development Mode}.
+
+    \section2 Install Momentics
+
+    Install the Momentics IDE by executing
+    \code
+     cd ~/Downloads/
+     chmod +x momentics-<your-version>.bin
+     ./momentics-<your-version>.bin
+    \endcode
+
+    Install the suggested API level. Other API levels can be added
+    \l{http://developer.blackberry.com/native/documentation/core/com.qnx.doc.ide.userguide/topic/update_ndk_ide.html}
+      {later}.
+    Select \e{Manage Devices} from the \e{Devices} drop-down menu. Create and Download the
+    BlackBerry ID token needed for deployment and testing. Enter your company name and choose a
+    password. Log in with your Black Berry ID and password in the pop-up window. Click \e{Next}
+    and \e{Finish} to generate a debug token and deploy it to your device.
+
+    Qt Creator 3.0 and later support the BlackBerry ID token and debug token management as well.
+
+    \section1 Verify Your Setup with a Sample App
+    \section2 In the Momentics IDE
+    Select a sample application in the Momentics IDE and click Download and Import. This will
+    download the sample and create a new project. Hit the green play button in Momentics to
+    run the application on your BlackBerry 10 device. The application will now start on your
+    BlackBerry 10 device.
+
+    \section2 In Qt Creator
+    See the
+    \l{http://qt-project.org/wiki/Qt-Creator-with-BlackBerry-10}{article}
+    Qt Creator with BlackBerry 10. Qt Creator 2.7 and later contain a plug-in which integrates
+    the BlackBerry 10 NDK and its tools into the development process as it is know to Qt
+    Creator users.
+
+    \section1 Simulator
+    You can download the Simulator from the Momentics IDE via the \gui{Devices} menu. Select
+    \gui{Manage devices} from the main toolbar in Momentics and switch to the Simulator tab.
+    The Simulator is available as separate download. For more details, see the this
+    \l{https://developer.blackberry.com/devzone/develop/simulator/}{article}
+    on the developer page. Installing the Simulator is optional. You most probably will test
+    and deploy applications on a BlackBerry 10 device directly, but sometimes using the Simulator
+    is more convenient. It also allows testing of your app on a configuration of a device which
+    you do not have.
+
+    If you work on the command line and use Qt 5.2 or later you have change the CPUVARDIR
+    environment variable to switch to Simulator as target:
+    \code
+    export CPUVARDIR=x86
+    \endcode
+
+    Going back to the device target:
+    \code
+    export CPUVARDIR=armle-v7
+    \endcode
+
+    Certainly you have to re-run qmake each time you change CPUVARDIR.
+
+    Note: You need to have VMware Player installed on your machine to run BlackBerry 10 Simulator.
+*/
+
+/*!
+    \page blackberryqt5.html
+    \title Qt 5 on BlackBerry 10
+    \brief Provides instructions how to use Qt 5 on BlackBerry.
+
+    Currently, Qt 5 is neither included in the BlackBerry 10 device software nor in the
+    BlackBerry 10 SDK. Nevertheless, Qt 5 on BlackBerry 10 can be used for developing
+    and publishing applications to BlackBerry World.
+
+    There are currently two options how you can use Qt 5 on BlackBerry 10:
+    \list
+     \li Use a binary overlay to add Qt 5 to an NDK installation
+     \li Make and use a custom Qt 5 build
+    \endlist
+
+    See sections below for more details.
+
+    \section1 Using a Binary Overlay to Add Qt 5 to an NDK Installation
+    Pre-built Qt 5 for BlackBerry is provided as a Qt Project delivery. The packages are available
+    \l{http://qtlab.blackberry.com/downloads/ndk_10.2.0_overlay/qt521_20140317/}
+      {here}.
+    The overlay gives you a prebuilt and tested package and saves the time for building
+    Qt 5 from scratch.
+
+    Please go through the README to learn how to install and use the packages. The provided
+    packages require the 10.2 Gold version of the BlackBerry 10 Native SDK. After the
+    installation, Qt 5 is automatically recognized and configured in Qt Creator 3.0 (and later)
+    and can be immediately used for application development.
+    Even though you do not need an own build, you still need to pay attention to a few details
+    described on this page.
+
+    Note: The overlay packages are not a part of the official NDK distributions by BlackBerry,
+    but as an add-on provided by the Qt Project. Be aware that you cannot mix Qt 5 code with
+    Cascades application framework APIs based on Qt 4.8. The Momentics IDE currently does not
+    support Qt 5 development.
+
+    \section1 Make Custom Qt 5 Builds
+
+    \list
+     \li Please make sure your working environment is set up:
+         \l{Getting Started with Qt for BlackBerry 10}{Setup for BlackBerry 10 development}
+     \li Build Qt 5 for BlackBerry 10: \l{Building Qt 5 for Blackberry 10}
+    \endlist
+*/
+
+/*!
+    \page blackberrybuild.html
+    \title Building Qt 5 for BlackBerry 10
+    \brief Provides instructions how to build Qt 5 for BlackBerry.
+
+    \section1 Setting up the Environment
+
+    See \l{Getting Started with Qt for BlackBerry 10}{Setup for BlackBerry 10 development}
+    for the introduction and further instructions.
+
+    \section1 Getting the Source
+
+    The approach we will take is to do an in-source build of the Qt 5 repositories that are
+    needed but to install them to a custom directory (\e{$HOME/development/qnx/qt5} in the
+    following example). Please also note that we clone and build git submodules separately.
+    This procedure is different to the builds for desktop platforms and allows to include
+    only those submodules which are relevant. Please adjust the paths to suit your setup as
+    needed.
+
+    First create a directory to hold the source code:
+    \code
+        cd $HOME/development
+        mkdir qt5
+        cd qt5
+    \endcode
+
+    The following repositories are used in regular builds for BlackBerry 10 in
+    \l{http://qtlab.blackberry.com/}{BlackBerry’s public CI}:
+    \list
+        \li qtbase
+        \li qtxmlpatterns
+        \li qtsensors
+        \li qtdeclarative
+        \li qtmultimedia
+        \li qtgraphicaleffects
+        \li qtconnectivity
+        \li qtquickcontrols
+    \endlist
+
+    This matches all essential modules, plus several add-on modules. QtWebKit is currently not
+    a part of the regular builds. Still, it is possible to build it, see
+    \l{http://qt-project.org/wiki/Building-QtWebKit-for-Blackberry}
+      {Building QtWebKit for Blackberry}
+
+    Other repositories known to build:
+    \list
+        \li qt3d (optional, provides 3D scenes using QML)
+        \li qtscript (optional, only needed when using the qtquick1 submodule)
+        \li qtlocation
+    \endlist
+
+    Then clone:
+    \code
+        git clone git://gitorious.org/qt/qtbase.git
+        git clone git://gitorious.org/qt/qtxmlpatterns.git
+        git clone git://gitorious.org/qt/qtsensors.git
+        git clone git://gitorious.org/qt/qtdeclarative.git
+        git clone git://gitorious.org/qt/qtmultimedia.git
+        git clone git://gitorious.org/qt/qtgraphicaleffects.git
+        git clone git://gitorious.org/qt/qtconnectivity.git
+        git clone git://gitorious.org/qt/qtquickcontrols.git
+    \endcode
+
+    \section1 Building qtbase
+
+    The process of building Qt 5 for BlackBerry devices is very similar to building it for any
+    other platform so it is worth having a quick read through the generic instructions for
+    building Qt 5 before proceeding.
+
+    Be sure that you have configured your environment to use the BlackBerry 10 NDK
+    (source the bbndk script on Linux for instance). This especially concerns setting
+    the right values in $PATH to pickup tools and the cross-compile tool-chain
+    provided in the NDK.
+
+    \section2 Linux and Mac OS X
+
+    First we need to configure Qt.
+
+    The examples below show a minimal set of configure options. You can see the full set of
+    configure options used in the \l{http://qtlab.blackberry.com/}{BlackBerry’s public CI}
+    in the raw console output of the \c qtbase build.
+    See this \l{http://qtlab.blackberry.com/job/qt-5-qtbase-stable/}{link} and then open the
+    raw \e{Console Output} for the last successful build for ARM or for x86.
+    \code
+        cd qtbase
+        ./configure -prefix $HOME/development/qnx/qt5 -xplatform blackberry-armle-v7-qcc -opengl es2 -nomake examples -nomake tests  -opensource -confirm-license -release
+    \endcode
+
+    Afterwards we simply build it by calling make and make install.
+    \code
+        make -j<N>
+        make install
+    \endcode
+
+    where \c{<N>} is the number of parallel make jobs to run. This is often set to \c{<No. of CPU cores + 1>}.
+
+    \section2 Windows
+    \code
+        C:\dev> cd qtbase
+        C:\dev\qtbase> configure -prefix C:\dev\qt5install -xplatform blackberry-armle-v7-qcc -opengl es2 -nomake examples -nomake tests -opensource -confirm-license -release
+    \endcode
+
+    If you want to work with the HTTPS protocol, add the \c{-openssl} option.
+
+    \section2 Mac OS X
+
+    This is almost the same as on Linux:
+    \code
+        $ cd qtbase
+        $ ./configure -prefix $HOME/development/qnx/qt5 -xplatform blackberry-armle-v7-qcc -opengl es2 -nomake examples  -nomake tests  -opensource -confirm-license -release -no-neon
+    \endcode
+
+    After this process, you should have a basic Qt 5 installation located in \c{$HOME/development/qnx/qt5}
+    or in \e{C:\dev\qt5install}, depending on your operating system.
+
+    You may now either move on to building your applications or continue here to install
+    some additional git submodules to gain access to additional features of Qt 5.
+
+    \section1 Building other Modules
+
+    If you want to build additional git submodules, make sure to do this in the right order,
+    because some git submodules depend on each other.
+
+    To build additional git submodules we need to use the qmake from our new Qt 5 installation
+    so we adjust the PATH environment variable accordingly:
+
+    \b{Linux and Mac OS X}: \c{export PATH=$HOME/development/qnx/qt5/bin:$PATH}
+
+    \b Windows: \c{C:\dev> set PATH=C:\dev\qt5install\bin;%PATH%}
+
+    Now for each of the additional git submodules that you wish to build, do the following:
+
+    \section2 Linux and Mac OS X
+    \code
+        cd <sub_module_name>
+        qmake
+        make -j<N>
+        make install
+    \endcode
+
+    \section2 Windows
+    \code
+        C:\dev> cd <sub_module_name>
+        C:\dev\submodule> qmake
+        C:\dev\submodule> mingw32-make -j
+        C:\dev\submodule> mingw32-make -j install
+    \endcode
+*/
+
+/*!
+    \page blackberryappdeploy.html
+    \title Deployment on BlackBerry 10
+    \brief Provides instructions how and deploy applications on BlackBerry.
+
+    Generally, this topic is well explained in the BlackBerry 10 documentation for native
+    application development.
+
+    \section1 Application Packaging
+    The page
+    \l{https://developer.blackberry.com/native/documentation/core/qt_package_deploy.html}
+    {Packaging, deployment and distribution}
+    is a good introduction to the tools and how to use them. In short, applications are packaged
+    in so called BAR files which are zip archives that contain additional meta-information.
+
+    \section1 Blackberry Application aRchive (BAR) Descriptor File
+    A part of this meta information is the content of the
+    \l{https://developer.blackberry.com/native/documentation/core/com.qnx.doc.native_sdk.devguide/topic/c_about_bar_app_descriptor_file.html}
+    {BAR application descriptor file}
+    which is an XML file. This file describes the content of the package and where this content
+    can be found. Other important meta-information is defined in this file, as well.
+
+    Qt Creator has an editor for the BAR application descriptor files which simplifies quite
+    some manual editing.
+
+    The content of the package may also include images, sounds and any other data files used by
+    the application in addition the the binary.
+
+    See
+    \l{https://developer.blackberry.com/native/documentation/core/com.qnx.doc.native_sdk.devguide/topic/r_blackberry_tablet_dtd_intro.html}
+      {full list of all elements in a BAR application descriptor file}
+
+    \section1 blackberry-nativepackager
+    Application packages are created by the command line tool \b{blackberry-nativepackager}
+    provided in the BlackBerry 10 NDK. This tool reads a BAR application descriptor file passed
+    as an argument and builds the application package accordingly.
+
+    Application packages can be built in development mode or can be built as signed packages.
+    Development mode applications require a \b{debug token} and can be installed and run on any
+    device with the same debug token as they were build with.
+
+    Signed packaged are usually used for publishing in BlackBerry World. They can also be
+    installed from the command line on any device in development mode and do not need a debug
+    token.
+
+    \section1 Where do the App Resources Land on the Device
+
+    \section2 Handling the Sand Box
+    Each application is installed in its own home folder on a dedicated partition. Shared folders
+    (those which contain data to be shared between apps) are mapped according to permissions
+    requested so that the app can access them under the standard paths. An important thing to
+    keep in mind is that all applications can access files only within the boundaries of
+    their \e sandboxes. When the app asks to access shared data, according folders become
+    available in app’s sandbox as well. See
+    \l{https://developer.blackberry.com/native/documentation/cascades/device_platform/data_access/file_system.html}
+      {Working with the file system}
+    for an overview of all sub-folders for different purposes in app’s home folder.
+
+    Applications cannot directly access any files outside their sandboxes. Even though it is
+    possible to package and deploy libraries with the application, it is not possible to deploy
+    any libraries into the system folders. Applications cannot share their libraries with other
+    applications either.
+
+    \section2 Packaging and Accessing the Files
+    Even though the article
+    \l{https://developer.blackberry.com/native/documentation/cascades/device_platform/data_access/file_system.html}
+      {Working with the file system}
+    explains how the sandbox model influences file access, it might not be clear from the
+    beginning how paths can actually be referred in the application code.
+
+    This line is the universal way to add any other content to the app package:
+    \code
+    <asset path="<local_path_to_files>/<local_file_name>"><on_device_path_to_files>/<on_device_file_name></asset>
+    \endcode
+
+    or even shorter:
+    \code
+    <asset path="<SOURCE>"><TARGET></asset>
+    \endcode
+
+    Lets assume you have an app which loads an image with Qt Quick . The application code is
+    located in the subfolder \e test_assets in your \e projects folder. The following line
+    adds this image to the BAR application descriptor file:
+    \code
+    <asset path="/Users/johndoe/projects/test_assets/qt-logo.png">qt-logo.png</asset>
+    \endcode
+
+    You also have to add QML files:
+    \code
+    <asset path="/Users/johndoe/projects/test_assets/qml">qml</asset>
+    \endcode
+
+    Note that we used absolute paths in the above examples, though relative paths
+    work, as well.
+
+    The key thing to know here is that the app installation folder is mapped to the folder
+    \e app/native in the application working directory (referred by QDir::currentPath(),
+    for example a \c . folder in the BAR application descriptor file maps to the \e{app/native/}.
+    folder. Our app would be installed for example in:
+    \code
+    /accounts/1000/appdata/com.example.test_assets.testDev_test_assetscd80795f
+    \endcode
+
+    The \e qt-logo.png lands here:
+    \code
+    /accounts/1000/appdata/com.example.test_assets.testDev_test_assetscd80795f/app/native/qt-logo.png
+    \endcode
+
+    The \e qml folder will be recursively copied to
+    \code
+    /accounts/1000/appdata/com.example.test_assets.testDev_test_assetscd80795f/app/native/qml/
+    \endcode
+
+    Our app has only one QML file which lands here:
+    \code
+    /accounts/1000/appdata/com.example.test_assets.testDev_test_assetscd80795f/app/native/qml/main.qml
+    \endcode
+
+    This QML code loads the image in \e main.qml as:
+    \code
+    Image {
+        source: "../qt-logo.png"
+        anchors.centerIn: parent
+    }
+    \endcode
+
+    Notice the \c ../ in the front of the file name. This is because the current folder of a Qt
+    Quick element is where its file was loaded from. We load \e main.qml this way:
+    \code
+    int main(int argc, char *argv[])
+    {
+        QGuiApplication app(argc, argv);
+        QQmlApplicationEngine engine;
+        engine.load(QUrl(QStringLiteral("app/native/qml/main.qml")));
+        return app.exec();
+    }
+    \endcode
+
+    \c Image assumes it is located in \c{app/native/qml/} and so needs to get one level up to get
+    to \c app/native/qt-logo.png.
+
+    One more thing to notice: the article
+    \l{https://developer.blackberry.com/native/documentation/cascades/device_platform/data_access/file_system.html}
+      {Working with the file system}
+    also talks about a dedicated \e{assets directory}. This is a bit confusing, since the \e asset
+    XML element in the BAR application descriptor file can refer to any file, but the
+    \e assets directory refers to the asset URI scheme in the Cascades framework.
+    Using Cascades UI components you can load image as:
+    \code
+    ImageView {
+        imageSource: "asset:///image.png"
+    }
+    \endcode
+
+    \section2 Prefer Using the Qt Resources
+    Using Qt resources (via the \c{qrc://} scheme) for all small read-only files and especially
+    for QML code files is a more preferred and convenient way! Accessing assets as files makes
+    only sense for large read-only files or files which will be changed/created by the app.
+
+    \section2 Viewing the Folders on the Device
+    In some cases, it might be needed to inspect the actual content of the folders directly on
+    the device. You can do this in an SSH shell in the File Inspector in the Momentics IDE.
+    The article
+    \l{http://qt-project.org/wiki/BlackBerry_Hints_n_Tips}{BlackBerry Hints and Tips}
+    shows how to use SSH with BlackBerry 10 along with
+    a few other hints and tips.
+
+*/
diff --git a/doc/src/platforms/platform-notes-blackberry.qdoc b/doc/src/platforms/platform-notes-blackberry.qdoc
new file mode 100644
index 00000000..9259574f
--- /dev/null
+++ b/doc/src/platforms/platform-notes-blackberry.qdoc
@@ -0,0 +1,113 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 BlackBerry Limited. All rights reserved.
+** 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 platform-notes-blackberry.html
+    \title Platform and Compiler Notes - BlackBerry
+    \contentspage Platform and Compiler Notes
+
+    This page lists features and restrictions that are particular for Qt on BlackBerry 10.
+
+    \section1 Supported Modules
+
+    Most Qt modules (essential and add-on) are supported except for instance Qt WebKit and
+    platform-specific ones. \l{BlackBerry supported modules} shows a detailed list of what
+    is supported and what isn't.
+
+    \section1 Application Window
+
+    The first top-level window that is shown will always be full screen. This parent-less
+    window serves as the application window, all other windows descend from it, even
+    if they don't have a parent from Qt's perspective. It is not possible to re-parent this
+    window to another window and when it is deleted any other window will vanish, as well.
+
+    In general, it is not possible to promote child windows to top level windows
+    (\l{QWindow::}{setParent()} with an argument of \c 0). If you do so, the window will
+    vanish along with its child windows.
+
+    \section1 Working Directory
+
+    Applications are restricted to their working directory (aka \e sandbox), they cannot
+    read or write outside this directory. Nevertheless absolute file paths are visible,
+    for instance calling QDir::currentPath() will initially yield
+    \c{/accounts/1000/appdata/namespace.application/}. This is the root directory an
+    application is confined to. A more detaild overview how to work with the file system
+    can be found in the corresponding
+    \l{Working with the file system}{BlackBerry 10 documentation}.
+
+    \section1 Application Lifecycle
+
+    A detailed overview of the states an application can move through can be found
+    \l{BlackBerry 10 application lifecycle}{here}.
+    Most of the transitions are mapped to Qt signals and events. For instance, if the
+    application is minimized a QGuiApplication::applicationStateChanged signal is emitted
+    with an argument of \c Qt::ApplicationInactive and a QExposeEvent is sent to the application
+    window. In the cases where this is not sufficient, a native event filter can
+    be use, that listens for navigator events. The navigator on the BlackBerry 10 OS
+    handles the entire application window lifecycle.
+
+    \section1 Peculiarities
+
+    This is a list of topics specific to Blackberry 10 which are discussed in their
+    own sections:
+
+    \list
+        \li \l{QAbstractNativeEventFilter::nativeEventFilter()}{Native events}
+        \li \l{Platform Limitations}{QSettings}
+        \li \l{Blackberry Peculiarities}{Cover windows}
+    \endlist
+
+    \section1 Multimedia
+    Restrictions that apply to Qt Multimedia on BlackBerry are described
+    \l{Qt Multimedia on BlackBerry}{here}.
+
+    \section1 Sensors
+
+    Most sensors are supported on BlackBerry (such as accelerometer, compass, magnetometer,
+    gyroscope, (IR) proximity, (ambient) light, orientation, rotation and holster sensors).
+    However, different devices might support a different set of sensors.
+    \l{ QSensor::sensorTypes()} will return a list of sensors that are supported on a
+    particular device.
+
+    \section1 Relationship to Cascades
+
+    Cascades is the prevailing UI framework for BlackBerry 10 development. It uses Qt (4.8)
+    C++ and QML as a base to provide a standard set of UI controls and other APIs tailored to
+    the BlackBerry 10 platform. If you are curious, take a look at the
+    \l{http://developer.blackberry.com/native/documentation/cascades/getting_started/intro/index.html}
+    {Introduction to Cascades} article.
+    Note that Cascades uses its own backend to render on the screen and uses only non-UI
+    parts of Qt. It is not possible to mix Qt and Cascades APIs to access the screen in
+    one application.
+
+    \section1 References
+
+    \list
+        \li \l{BlackBerry 10 device characteristics}
+    \endlist
+
+*/
diff --git a/doc/src/platforms/supported-platforms.qdoc b/doc/src/platforms/supported-platforms.qdoc
index a25a8d71..346fd93e 100644
--- a/doc/src/platforms/supported-platforms.qdoc
+++ b/doc/src/platforms/supported-platforms.qdoc
@@ -75,7 +75,7 @@
     The following platforms also support Qt:
 
     \list
-        \li \l{Qt for BlackBerry}{BlackBerry 10}
+        \li \l{Qt for BlackBerry 10}{BlackBerry 10}
         \li \l{Sailfish OS}
     \endlist
 
@@ -168,6 +168,7 @@
     \li \l{Deploying Qt Applications}
         \list
             \li \l{Platform and Compiler Notes - Android#Deployment}{Android}
+            \li \l{Deployment on BlackBerry 10}{BlackBerry}
             \li \l{Qt for iOS}{iOS}
             \li \l{Qt for Linux/X11 - Deployment}{Linux/X11}
             \li \l{Qt for Mac OS X - Deployment}{Mac OS X}