diff options
Diffstat (limited to 'doc/src/platforms/blackberry.qdoc')
| -rw-r--r-- | doc/src/platforms/blackberry.qdoc | 514 |
1 files changed, 0 insertions, 514 deletions
diff --git a/doc/src/platforms/blackberry.qdoc b/doc/src/platforms/blackberry.qdoc deleted file mode 100644 index 53a1d86c0..000000000 --- a/doc/src/platforms/blackberry.qdoc +++ /dev/null @@ -1,514 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2014 BlackBerry Limited. All rights reserved. -** Contact: http://www.qt.io/licensing/ -** -** 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 The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/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 - \badcode - 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://wiki.qt.io/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: - \badcode - export CPUVARDIR=x86 - \endcode - - Going back to the device target: - \badcode - 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: - \badcode - 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://wiki.qt.io/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: - \badcode - 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 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. - \badcode - 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. - \badcode - 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 - \badcode - 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 OS X - - This is almost the same as on Linux: - \badcode - $ 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 \c{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 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 OS X - \badcode - cd <sub_module_name> - qmake - make -j<N> - make install - \endcode - - \section2 Windows - \badcode - 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: - \badcode - <asset path="<local_path_to_files>/<local_file_name>"><on_device_path_to_files>/<on_device_file_name></asset> - \endcode - - or even shorter: - \badcode - <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: - \badcode - <asset path="/Users/johndoe/projects/test_assets/qt-logo.png">qt-logo.png</asset> - \endcode - - You also have to add QML files: - \badcode - <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: - \badcode - /accounts/1000/appdata/com.example.test_assets.testDev_test_assetscd80795f - \endcode - - The \e qt-logo.png lands here: - \badcode - /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 - \badcode - /accounts/1000/appdata/com.example.test_assets.testDev_test_assetscd80795f/app/native/qml/ - \endcode - - Our app has only one QML file which lands here: - \badcode - /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://wiki.qt.io/BlackBerry_Hints_n_Tips}{BlackBerry Hints and Tips} - shows how to use SSH with BlackBerry 10 along with - a few other hints and tips. - -*/ |