用 Qt Creator环境 为 BlackBerry 10 开发 Qt应用

转自：http://qt-project.org/wiki/Setting-up-Qt-Creator-for-BlackBerry-and-QNX

一、在开发前需要下载以下开发工具

黑莓NDK: The BlackBerry 10 Native SDK，下载地址是developer.blackberry.com 

• 黑莓模拟器：BlackBerry 10 Dev Alpha Simulator

  如果没真机BlackBerry DevAlpha device的话，下载地址是developer.blackberry.com 

• 签名申请：BlackBerry signing code keys[blackberry.com] , 如果用模拟器开发的话，这一步不是必须的

• QtCreator 2.7 (the required QNX plugin should be enabled by default). You can either clone it[qt.gitorious.org] or download a binary installer from[qt-project.org]. You can also download a recent build from Jenkins[builds.qt-project.org]. 

Enabling development mode

First of all, you have to enable development mode to be able to access your device to deploy and test software on it.

Refer to this article to see how to do that: http://developer.blackberry.com/native/documentation/bb10/enable_development_mode.html/

Note: if you’re under Linux, there’s one more step to be able to connect to the target machine: go to Settings->Storage and set “Usb connection” to “Connect to Windows” or “Connect to Mac”.

Getting the BlackBerry code signing keys

You need to obtain the BlackBerry signing code keys in order to sign your application, or to create a debugToken to run unsigned applications in development mode. The debugToken enables you to test your application on the device before signing it. Once your application is ready for publishing you should sign it.

Note: if you are using the BlackBerry 10 Dev Alpha Simulator, you don’t need to use the debugToken. So you can skip related steps below.

After you submitted a request to get the BlackBerry code signing keys, you should receive two “.cjs” registration files by email within the next few hours.

• “client-RDK-*.csj” �C used to sign your applications and publish to the BlackBerry App World storefront. 

• “client-PBDT-*.csj” �C used to generate a debug token that you can use to test your application on a device. 

Note: if you are using Qt Creator 2.7 or higher, you can register directly using the new BlackBerry Settings page as explained in the next section. So you can skip the instructions below.

Once you receive those files, register them with the RIM Signing Authority using the following command line:

1. $ blackberry -signer  - register -csjpin  <csj pin > -storepass  <KeystorePassword > <client -RDK -xxxxxx. csj file > <client -PBDT -xxxxx. csj file >

 

where the “<cjs pin>” is the PIN you specified on the web form when requesting the code signing keys and the “<KeystorePassword>” is a password you specify for the keystore.

For more details about signing please refer to Signing Setup Guide[developer.blackberry.com]

Then you create a debugToken file for your device as follows:

1. $ blackberry -debugtokenrequest  -storepass  <KeystorePassword > -devicepin  <device PIN > <debug_token_file_name. bar >

 

You can find the “<device PIN>” on your device or in simulator under “Settings \-> About \-> Hardware”

Your next steps are to install the new debugToken into your device :

1. $ blackberry -deploy  -installDebugToken  <path to debug token > -device  <IP address of device > -password  <device password >

 

For more details on the debugToken please refer to this article[developer.blackberry.com]

Configuring QtCreator

The QtCreator 2.7 brings new features for the BlackBerry 10 plugin (currently called “Qnx”) that enables you to easily create, build, deploy and debug your application directly from the IDE. Please make sure you use the 2.7 version or a recent build of QtCreator. Here are the new features that the BlackBerry 10 plugin provides for 2.7:

• Easy setup of the your BlackBerry 10 development environment (Kits, Qt Version, Compiler, …). 

• Support for the BlackBerry Signing code process to register and create a developer certificate and generate a debugToken to upload your apps into the device. 

• UI editor for the bar descriptor file to easily manage the application’s appearance and behavior when running on the device. 

Using QtCreator 2.7

As previously mentioned you can either download a binary installer[qt-project.org] or clone and build it on your own[qt.gitorious.org].

Note: If you are using QtCreator 2.6 we highly recommend you to download the version 2.7 which hugely simplifies the setup of your BlackBerry 10 plugin. By consequence, we won’t cover the use of QtCreator 2.6 in the current article.

If you already have a QtCreator 2.7 installed on you machine, please follow the steps below:

• Select Tools > Options > BlackBerry > NDK (on Mac: Preferences > BlackBerry > NDK) and set the path to your NDK. This will generate a Qt version, a Compiler and two Kits (one for the device and another for the simulator) based on your NDK. 

• Select Tools > Options > BlackBerry > Keys (on Mac: Preferences > BlackBerry > Keys) to register and create a developer certificate. To register you need to set the path to your registration files and the PIN code you specified when requesting the signing keys. 

• Select Tools > Options > Devices > Add > Blackberry Device (on Mac: Preferences > Devices > Add > Blackberry Device) to add a BlackBerry Device. You can add either the physical device or the simulator. 

• Create and upload a debug token bar file when adding the device from the wizard. 

Note: The signing code support in QtCreator is under development and will be improved in the future. 

Using a recent QtCreator build

You can also download a nightly build of QtCreator from http://builds.qt-project.org.

Unix (Mac/Linux): http://builds.qt-project.org./job/qt-creator-unix-snapshot/
Windows: http://builds.qt-project.org./job/qt-creator-windows-snapshot/

It contains some improvements planned for 2.8 which are not available in the 2.7.x release versions.

Known issues with QtCreator 2.7

Below are few known issues with the Qnx plugin in QtCreator 2.7 release, which should be fixed in the next 2.7.1 release:

• If you create a new project, select a BlackBerry Kit and build in a release mode only, QtCreator will fail to create the package as it will try to find the bar-descriptor file in a debug build repository. Make sure you selected a debug build to avoid this issue. 

• If you create a Qt5 project, QtCreator will generate a bar descriptor in order to create the application’s package. You need to add the following lines to your bar descriptor in order for the application to run correclty:
  

  1. <arg >-platform </arg >
  2. <arg >qnx </arg >

   

   

We recommend to use a nightly Qt Creator build which already contains fixes for the issues above.

Creating Your First BlackBerry 10 Qt Project

You can create a Qt application by selecting one of project templates in the “new project” wizard. Additionally, The BlackBerry plugin provides extra templates for Cascades projects and Qt GUI applications using BlackBerry 10 custom styles. 

For example, if you create a Qt Quick Application and use the Kit you defined for BlackBerry Qt Creator will automatically generate a bar descriptor file and ask you if you want to add it into your project. You can then use the bar descriptor UI editor to edit your application’s bar descriptor file. 

Deploying Qt5 Applications

If you are using Qt5, Qt Creator will generate a bar descriptor file to deploy your Qt5 libraries and create the application’s package. As currenlty Qt5 libraries are not shipped in the BlackBerry 10 devices, you need to deploy them into your package.

The following lines in the generated bar descriptor will copy and deploy your Qt5 libraries, imports and plugins automatically from your Qt5 installation directory:

1. <env value = "app/native/imports" var = "QML2_IMPORT_PATH" />
2. <env value = "app/native/plugins" var = "QT_PLUGIN_PATH" />
3. <env value = "app/native/lib" var = "LD_LIBRARY_PATH" />
4.     ...
5. <asset path = "%QT_INSTALL_PLUGINS%" >plugins </asset >
6. <asset path = "%QT_INSTALL_QML%" >imports </asset >
7. <asset path = "%QT_INSTALL_LIBS%" >lib </asset >

 

Note that, for security reasons, the nativepackager doesn’t consider symbolic links. This will cause each Qt library to be copied four times and increase significantly the package size. We will provide in the near future a bar file containing the Qt5 libraries, so that you don’t have to deploy them into your packages.

Note: You can exclude the Qt libraries you don’t use to decrease your package size. For that, you can use the <exclude> element and sepcify the libraries to exclude as shown in the example below: 

1. <env value = "app/native/lib" var = "LD_LIBRARY_PATH" />
2.     ...
3. <asset path = "%QT_INSTALL_LIBS%" >
4. <exclude name = "libQt5Xml.so.5.1.0" />
5. <exclude name = "libQt5QuickParticles.so.5.1.0" />
6. <exclude name = "libQt5Test.so.5.1.0" />
7.         ...
8. lib
9. </asset >

 

Editing Your Bar Descriptor File 

The “bar-descriptor.xml” file specifies the parameters for identifying, installing, and launching native applications on BlackBerry 10. It mainly contains information about the application author, id, icons and other properties and is used to create the BAR file or BAR package. A BAR package is a installation package of an application for the BlackBerry 10 platform. “BAR” stands for “ B lackberry A pplication a R chive”. For more details please refer to this page[developer.blackberry.com]

QtCreator 2.7 provides a new UI editor to easily edit your bar descriptor and manage your application’s behavior and appearance.

Note: the generated bar descriptor file will be called bar-descriptor.xml and will be used by QtCreator to generate a final bar descriptor in the build directory to package your application.

If you run the application now, QtCreator will create the bar package, connect to the device or to the simulator and launch your application. You can also do these steps using commands in a shell, see the next section for more details.

For performance reasons, the log output from qWarning, qDebug, etc is captured by the “slog2” logging system on BlackBerry 10 instead of plain text files in the file system. In the actual release the messages will appear unfiltered in the “Application Output”.

Package and Deploy Your Application Using Command line.

You can use NDK command line tools to package and deploy your application instead QtCreator if needed:

• create the package in devMode: 

1. $ blackberry -nativepackager   -devMode   -package  <package_name. bar > <bar -descriptor. xml > -debugToken  <debug_Token_file. bar >

 

• create the package in Signing mode: 

1. $ blackberry -nativepackager  -package   <package_name. bar > <bar -descriptor. xml >

 

• sign your application (not needed in the devMode): 

1. $ blackberry -signer  -storepass  <KeyStorePassword > <package_name. bar >

 

• deploy on the device: 

1. $ blackberry -deploy  -installApp  -package  <package_name. bar > -device  <device_ip > -password  <device_password >

 

• in case you don’t like what you see, you can remove the application: 

1. $ blackberry -deploy  -uninstallApp  -package  <package_name. bar > -device  <device_ip > -password  <device_password >

 

Or just deploy the next version. 

Building and running Cascades based applications from Qt Creator

These configuration has been tested on Linux Debian Wheezy (64 bits) and Opensuse 12.2 with BB10 Gold NDK and deployment on a Simulator and device.

In order to build Cascades applications, you need to adapt your bar-descriptor.xml file, as well as tweaking Qt Creator settings a bit. From now, we assume that you are able to build a Qt Quick application, and able to deploy it. Those using simulator and that are unable to launch the application, even if it compiles and is deployed, should refer to the next section.

Note that using Cascades in your application is more involved than just adding “import bb.cascades 1.0” to your QML files. See the Cascades Documentation[developer.blackberry.com] to learn how to write Cascades based applications.

Packaging and deployment options

When using cascades, some precautions have to be taken for packaging your application. You first have to respect a specific folder layout, where all shipped files, that includes images files like icons, and QML files, should be in a subfolder called assets.

The bar-descriptior.xml file should also be adapted to take the different targets in account. Here is an example of descriptor file including only the simulator as a debug target

1. <?xml version = '1.0' encoding = 'utf-8' standalone = 'no'? >
2. <qnx  >
3. <id >com. example. app </id >
4. <name >app </name >
5. <versionNumber >1.0.0 </versionNumber >
6. <description >DESCRIPTION </description >
7. <initialWindow >
8. <systemChrome >none </systemChrome >
9. <transparent > false </transparent >
10. <autoOrients > true </autoOrients >
11. <aspectRatio >landscape </aspectRatio >
12. </initialWindow >
13. <env value = "app/native/imports" var = "QML_IMPORT_PATH" />
14. <env value = "app/native/qml" var = "QML2_IMPORT_PATH" />
15. <env value = "app/native/plugins:/usr/lib/qt4/plugins" var = "QT_PLUGIN_PATH" />
16. <env value = "app/native/lib:/usr/lib/qt4/lib/" var = "LD_LIBRARY_PATH" />
17. <action  system = "true" >run_native </action >
19. <configuration name = "Simulator-Debug" >
20. <platformArchitecture >x86 </platformArchitecture >
21. <asset path = "%SRC_DIR%/path/to/build/folder/o-g/app" entry = "true" type = "Qnx/Elf" >app </asset >
22. </configuration >
24. <!-- omit the above  "Simulator-Debug" configuration section and add the line below  if using device only
25. <asset path = "app" entry = "true" type = "Qnx/Elf" >app </asset >
26. -->
28. <asset path = "%SRC_DIR%/assets" >assets </asset >
29. </qnx >

 

You can take inspiration on descriptor files that the SDK generates to get other targets. But take care of the o-g folder in which the debug binaries will be compiled for the simulator. Other binaries have their own folder.

In the project file, you needs to add cascades options. You can also add import path, that provides autocompletion in C++ editor. QML autocompletion does not work out of box for now, but a workaround exists[qt-project.org]. The following template contains all the settings that should be added.

1. TEMPLATE  = app
2. TARGET  = app
3. QT = ...
4. CONFIG += cascades10
6. # Horrible workaround because INCLUDEPATH do not work with
7. # absolute path under Linux + QtCreator 2.6 ???
8. INCLUDEPATH  += .. /.. /.. /relative /path /<target >/qnx6 /usr /include
9. INCLUDEPATH  += .. /.. /.. /relative /path /<target >/qnx6 /usr /include /qt4
11. HEADERS  =   ...
13. SOURCES +=  ...
15. OTHER_FILES +=  bar -descriptor. xml \
16.                             assets /main. qml \
17.                             ...

 

QMake settings

Some additional settings have to be passed to qmake in order to make the compilation to work. First, if you didn’t add the BB10 kit, you should add it. It will provide automatically the compilation recipe and the testing on a device. In order to compile cascades based applications, you need to add a QMake option, that is

1. CONFIG +=device

 

for a device, or

1. -spec blackberry -x86 -qcc CONFIG +=simulator

 

for the simulator.

With these options, compiling a cascades based application, and deploying it should work.

How to make Qt Creator work with the Simulator

Setting the simulator as a device is easy, and can be done as if it was a real device. However, the simulator is X86-based, and the default settings for compiling a Qt project with Qt Creator are those for arm devices. In order to compile for X86, you have to change the MKSPEC, and it is done by passing

1. -spec blackberry -x86 -qcc

 

to the QMake additionnal arguments. With this spec set, it will override the default spec and compile for X86.

Application permission

You can add some permission to the application by tweaking the bar-description.xml file by adding the line

1. <permission >permission_identifier </permission >

 

or the following line for permission identifier that is mark * in the list below

1. <permission  system = "true" >permission_identifier </permission >

 

Here’s a list of permission identifier

• Permission �C Identifier

• Internet �C access_internet 

• Location �C access_location_services 

• Microphone �C record_audio 

• Notebooks �C access_pimdomain_notebooks 

• Post Notifications �C post_notification 

• Push �C _sys_use_consumer_push * 

• Run when background �C run_when_backgrounded 

• Shared Files �C access_shared 

• Text Messages �C access_sms_mms 

• Blackberry Messenger �C bbm_connect 

• Calender �C access_pimdomain_calendars 

• Camera �C use_camera 

• Contacts �C access_pimdomain_contacts 

• Device Identifying Information �C read_device_identifying_information 

• Email and PIN messages �C access_pimdomain_messages 

• GPS Location �C read_geolocation