path: root/doc/src/platforms/blackberry.qdoc

/****************************************************************************
**
** 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.

*/