Updated Branches: refs/heads/master 34f9eb6e9 -> dfe7d6ce7
[CB-4347] Fix merge issues in bb10 platform guide Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/dfe7d6ce Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/dfe7d6ce Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/dfe7d6ce Branch: refs/heads/master Commit: dfe7d6ce740af1d4f075e96c1c8060f710ed6663 Parents: 34f9eb6 Author: Bryan Higgins <[email protected]> Authored: Mon Jul 29 23:06:03 2013 -0400 Committer: Bryan Higgins <[email protected]> Committed: Mon Jul 29 23:06:03 2013 -0400 ---------------------------------------------------------------------- .../3.0.0/guide/platforms/blackberry10/index.md | 165 +++++++++---------- .../edge/guide/platforms/blackberry10/index.md | 96 ++++------- 2 files changed, 117 insertions(+), 144 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/dfe7d6ce/docs/en/3.0.0/guide/platforms/blackberry10/index.md ---------------------------------------------------------------------- diff --git a/docs/en/3.0.0/guide/platforms/blackberry10/index.md b/docs/en/3.0.0/guide/platforms/blackberry10/index.md index f3c35cf..7695c8d 100644 --- a/docs/en/3.0.0/guide/platforms/blackberry10/index.md +++ b/docs/en/3.0.0/guide/platforms/blackberry10/index.md @@ -19,147 +19,146 @@ license: Licensed to the Apache Software Foundation (ASF) under one # BlackBerry 10 Platform Guide -This guide shows how to set up your SDK development environment to -deploy Cordova apps for BlackBerry 10 devices. See the following for more -detailed platform-specific information: +This guide shows how to set up your development environment to build and deploy Cordova apps for BlackBerry 10 devices. -* BlackBerry 10 Plugins -* BlackBerry 10 Command-line Tools - -The command-line tools above refer to versions prior to Cordova 3.0. -See The Cordova Command-line Interface for information about the -current interface. +For previous versions of BlackBerry, you need to use a different set of command-line tools, described in BlackBerry Platform Guide. ## Requirements -Cordova for BlackBerry has the following software requirements: +The development environment is available on Windows, Mac and Linux. + +Developers should use the `cordova` utility in conjunction with the Blackberry Native SDK. See The Command-line Interface for information how to install `cordova`, add projects, then build and deploy. + +## Install the BlackBerry Native SDK + +The BlackBerry Native SDK is available from [developer.blackberry.com](http://developer.blackberry.com/native/download/). + +After installing the BlackBerry Native SDK, its tools must be added to your system path. + +### Windows + +Go to My Computer → Properties → Advanced → Environment Variables + +Append to PATH based on where you installed the Native SDK, for example: -- Windows XP (32-bit) or Windows 7 (32-bit and 64-bit) or Mac OSX 10.6.4+ -- node.js (> 0.9.9) [Download node.js now](http://nodejs.org/) -- BlackBerry 10 Native SDK. [Download the BlackBerry 10 Native SDK now.](http://developer.blackberry.com/native/download/) + ;C:\bbndk\host_10_1_0_132\darwin\x86\usr\bin\ -## Setting up your signing keys +### Mac/Linux -Before starting development, you'll need to register for your code signing key and debug token. The signing key allows you to sign your completed app so that you can distribute it through BlackBerry World. The debug token allows you to test an unsigned app on a BlackBerry 10 device. You do not need to create and install the debug token yourself; if you supply the keystore password, the build script will create and install the debug token for you. +Edit the ~/.bash_profile file, adding a line such as the following, depending on where the Native SDK was installed: -- [Register for your code signing key now.](https://www.blackberry.com/SignedKeys/codesigning.html) -- [Set your computer up for code signing. ](http://developer.blackberry.com/html5/documentation/set_up_for_signing.html) -- [Learn more about debug tokens.](http://developer.blackberry.com/html5/documentation/running_your_bb10_app_2008471_11.html) + $ export PATH=${PATH}:/Applications/bbndk/host_10_1_0_132/darwin/x86/usr/bin/ -## Creating your project +Then run the following to apply the change immidiately: -To create a new project, you use the `create` command to set up the folder structure for your app. + $ source ~/.bash_profile -1. On the command line, navigate to the folder where you extracted Cordova. -2. Run the `create` command using the following syntax: +## Set up for Signing - bin/create <path-to-project> +If you wish to test on a device or distribute apps through BlackBerry World, your system must be setup for code signing. -This command creates the folder structure for your project at the specified location. All of your project resource files should be stored in the *<path-to-project>*/www folder, or in a subfolder within it. +To obtain a signing key, go to the BlackBerry website and make sure to retain the password you specify. Then run the `blackberry-signer` utility that is included with the BlackBerry Native SDK. -## Adding and managing targets +Detailed instuctions can be found here: -A target refers to a BlackBerry device or emulator that you will use to test your app. Targets are added directly to your project; you can add multiple targets to your project, each with a unique name. Then, when you want to deploy your app to a particular target, you can simply refer to that target by name when you run your script. +* [Register for your code signing key.](https://www.blackberry.com/SignedKeys/codesigning.html) +* [Set up your system for code signing.](https://developer.blackberry.com/html5/documentation/signing_setup_bb10_apps_2008396_11.html) -###Add a target +## Create a Project -To add a target, on the command line, type the following command: +Use the `cordova` utility to set up a new project, as described in The Command-line Interface. For example, in a source-code +directory: + + $ cordova create hello com.example.hello + $ cd hello + $ cordova platform add blackberry10 + $ cordova build - <path-to-project>/cordova/target add <name> <ip-address> [-t | --type <device | simulator>] [-p | --password <password>] [--pin <device-pin>] +## Deploy to Emulator -where +If you wish to run a device emulator, download and install the BlackBerry 10 Simulator. -- `<name>` specifies a unique name for the target. -- `<ip-address>` specifies the ip address of the BlackBerry device or emulator. -- `-t <device | simulator>` specifies the target type. If not provided, the default value is device. -- `-p|--password <password>` specifies the password for the device or emulator. This is required only if the device or emulator is password protected. -- `--pin <device-pin>` specifies the PIN of the BlackBerry device, which identifies that device as a valid host for the debug token. This argument is required only if you are creating a debug token. +* [Download](http://developer.blackberry.com/native/download/) +* [Getting Started](http://developer.blackberry.com/devzone/develop/simulator/blackberry_10_simulator_start.html) -###Remove a target +Before testing an app on either an emulator or a device, you need to add a _target_ to your project. Each is identified with a unique name, and associated with an IP address. You need to get the IP address from the emulator before you use it to view apps. -To remove a target, on the command line, type the following command: +Launch the emulator image, then choose __Settings__ from the home screen: - <path-to-project>/cordova/target remove <name> + -###Set a target as the default +Navigate to the __Security and Privacy → Development Mode__ section, enable the option, and obtain the IP address: -To specify a specific target as the default, on the command line, type the following command: + - <path-to-project>/cordova/target default <name> +An additional set of command-line utilities are included when you set up the BlackBerry 10 platform for your project. The following command, in this case invoked from the project top-level directory, associates a target named _emu_ with the IP address displayed above. -## Building your app +Windows -To build your app, run the build script. You can build the app in either release mode or in debug mode. + $ platforms\blackberry10\cordova\target.bat add emu 169.254.0.1 -t simulator -- When you build the app in release mode, you are preparing it for distribution through BlackBerry World. The script packages your app resources and plugins together in a .bar file, then signs the app. -- When you build the app in debug mode, you are preparing it to be tested. The script packages your app resources and plugins together in a .bar file, but does not sign it. The script can also deploy the app onto a previously defined target. If you have not already created and installed a debug token, you can supply the keystore password, and the build script will create and install the debug token for you as well. +Mac/Linux - Debug mode also enables Web Inspector for the app, which allows you to remotely inspect the source code. A prompt displays the URL that you can use to connect to and inspect your app. For more information on using Web Inspector, see [Debugging using Web Inspector](http://developer.blackberry.com/html5/documentation/web_inspector_overview_1553586_11.html). + $ platforms/blackberry10/cordova/target add emu 169.254.0.1 -t simulator -###Build your app in release mode +Then, run the `emulate` command to view the app: -To build your app in release mode, on the command line, type the following command: + $ cordova emulate blackberry10 - <path-to-project>/cordova/build release -k|--keystorepass <password> [-b|--buildId <number>] [-p|--params <params-JSON-file>] +## Deploy to Device -where +To deploy to a device, make sure it is plugged into your computer. Enable development mode and obtain the IP address as desribed in the emulator section above. You will also need to obtain the PIN from the the __Settings__ application under __About → Hardware__. -- `-k|--keystorepass <password>` specifies the password you defined when you configured your computer to sign applications. -- `-b|--buildId <number>` specifies the build version number of your application. Typically, this number should be incremented from the previous signed version. This argument is optional. -- `-p|--params <params-JSON-file>` specifies a JSON file containing additional parameters to pass to downstream tools. This argument is optional. + -###Build your app in debug mode +Run the target command-line utility to associate a name with an IP address, device password and PIN. -To build your app in release mode, on the command line, type the following command: +Windows - <path-to-project>/cordova/build debug [<target>] [-k|--keystorepass <password>] [-p|--params <params-JSON-file>] [-ll|--loglevel <error|warn|verbose>] + $ platforms\blackberry10\cordova\target.bat add mydevice 169.254.0.1 -t device --password 123456 --pin FFFF972E -where +Mac/Linux -- `<target>` specifies the name of a previously added target. If `<target>` is not specified, the default target is used, if one has been created. This argument is only required if you want the script to deploy your app to a BlackBerry device or emulator and you have not created a default target. Additionally, if `<target>` is a device, then that device must be connected to your computer by USB connection or be connected to the same Wi-Fi network as your computer. -- `-k|--keystorepass <password>` specifies the password you defined when you configured your computer to sign applications. This password is also used to create your debug token. This argument is only required if you want the script to create and install the debug token for you. -- `-p|--params <params-JSON-file>` specifies a JSON file containing additional parameters to pass to downstream tools. -- `-ll|--loglevel <level>` specifies the log level. The log level may be one of `error`, `warn`, or `verbose`. + $ platforms/blackberry10/cordova/target add mydevice 169.254.0.1 -t device --password 123456 --pin FFFF972E -Note that all of these parameters are optional. If you have previously defined a default target (and installed a debug token, if that target is a BlackBerry device), you can run the script with no arguments, and the script will package your app and deploy it to the default target. For example: +--password refers to the password to unlock the device - <path-to-project>/cordova/build debug +--pin refers to the device PIN obtained from the Settings application -## Deploying an app +Then, run the `run` command to view the app: -You can test your app using either a BlackBerry device or an emulator. Before deploying your app, you must first create a target for the device or emulator you want to deploy your app to. + $ cordova run blackberry10 -The run script will first build your app. If you intend to deploy an app to a physical device for testing, you must first install a debug token on that device. If you specify the `--keystorepass <password>` argument when running the run script, the script will create and install the debug token for you. You do not need a debug token to test your app on an emulator, even if that app is unsigned. +If a debug token has not yet been created for this device, an error message will prompt you to use the platform run script with the password you provided when registering for signing keys. -To deploy your app to a device or emulator, on a command line type the following command: +Windows - <path-to-project>/cordova/run <target> [--no-build] + $ platforms\blackberry10\cordova\run.bat --device --keystorepass mysecret -where -- `<target>` specifies the name of a previously added target. If `<target>` is a device, then that device must be connected to your computer by USB connection or be connected to the same Wi-Fi network as your computer. +Mac/Linux -- `-no--build` will use the most recently built version of the application rather than re-building. This is useful to test an application in release mode. + $ platforms/blackberry10/cordova/run --device --keystorepass mysecret -## Adding and managing plugins +## Debugging with WebInspector -To add additional functionality that is outside of the core features of Cordova, you'll need to add plugins. A plugin represents a set of APIs that provide access to additional features of the platform. +When debugging on the device or a simulator, you may run WebInspector remotely to view the application's internal state. -In order to use a plugin, you must first add it into your project. Once added into your project, the plugin will be bundled with your project during the build process, to ensure that your app has access to all the APIs it needs. +A prompt displays the URL that allows you to connect to your app with a standard web browser. -###Add a plugin +For more information, see [Debugging using WebInspector](http://developer.blackberry.com/html5/documentation/web_inspector_overview_1553586_11.html). -To add a plugin, on the command line, type the following command: +## Building a Release Version - <path-to-project>/cordova/plugin add <path to plugin> +By default, running the `cordova build` command creates an unsigned _.bar_ package file suitable for testing on a device or simulator. -###Remove a plugin +You need to run a different `build` command to create a release version suitable for distribution through BlackBerry World. This command uses the following syntax: -To remove a plugin, on the command line, type the following command: +Windows - <path-to-project>/cordova/plugin rm <name> + $ platforms\blackberry10\cordova\build.bat --release --keystorepass mysecret -###View a list of installed plugins +Mac/Linux -To view a list of installed plugins, on the command line, type the following command: + $ platforms/blackberry10/cordova/build --release --keystorepass mysecret - <path-to-project>/cordova/plugin ls +--keystorepass specifies the password you defined when you configured your computer to sign applications. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/dfe7d6ce/docs/en/edge/guide/platforms/blackberry10/index.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/guide/platforms/blackberry10/index.md b/docs/en/edge/guide/platforms/blackberry10/index.md index 5867ac1..7695c8d 100644 --- a/docs/en/edge/guide/platforms/blackberry10/index.md +++ b/docs/en/edge/guide/platforms/blackberry10/index.md @@ -29,38 +29,31 @@ The development environment is available on Windows, Mac and Linux. Developers should use the `cordova` utility in conjunction with the Blackberry Native SDK. See The Command-line Interface for information how to install `cordova`, add projects, then build and deploy. -- Windows XP (32-bit) or Windows 7 (32-bit and 64-bit) or Mac OSX 10.6.4+ - -- node.js (> 0.9.9) [Download node.js now](http://nodejs.org/) - -- BlackBerry 10 Native SDK. [Download the BlackBerry 10 Native SDK now.](http://developer.blackberry.com/native/download/) +## Install the BlackBerry Native SDK The BlackBerry Native SDK is available from [developer.blackberry.com](http://developer.blackberry.com/native/download/). -After installing the BlackBerry Native SDK, its tools must be added to your system path. Either manually add the bin directory to your path or run the following scripts from the directory where you installed the NDK: - -Windows +After installing the BlackBerry Native SDK, its tools must be added to your system path. - bbndk-env.bat +### Windows -To create a new project, you use the `create` command to set up the directory structure for your app. +Go to My Computer → Properties → Advanced → Environment Variables -1. On the command line, navigate to the directory where you extracted Cordova. +Append to PATH based on where you installed the Native SDK, for example: -2. Run the `create` command using the following syntax: + ;C:\bbndk\host_10_1_0_132\darwin\x86\usr\bin\ -## Set up Emulators +### Mac/Linux -This command creates the directory structure for your project at the specified location. All of your project resource files should be stored in the *<path-to-project>*/www directory, or in a subdirectory within it. +Edit the ~/.bash_profile file, adding a line such as the following, depending on where the Native SDK was installed: -* [Download](http://developer.blackberry.com/native/download/) -* [Getting Started](http://developer.blackberry.com/devzone/develop/simulator/blackberry_10_simulator_start.html) + $ export PATH=${PATH}:/Applications/bbndk/host_10_1_0_132/darwin/x86/usr/bin/ -- '<path-to-project>' specifies the directory you want the project created in +Then run the following to apply the change immidiately: -- '<project-package>' specifies a reverse domain style identifier + $ source ~/.bash_profile -- '<project-name>' specifies the apps display name +## Set up for Signing If you wish to test on a device or distribute apps through BlackBerry World, your system must be setup for code signing. @@ -76,22 +69,17 @@ Detailed instuctions can be found here: Use the `cordova` utility to set up a new project, as described in The Command-line Interface. For example, in a source-code directory: - cordova create hello com.example.hello - cd hello - cordova platform add blackberry10 - cordova build + $ cordova create hello com.example.hello + $ cd hello + $ cordova platform add blackberry10 + $ cordova build -*Note*: the create command bootstraps dependency installation through the 'npm install' command. Depending on installation directory and system permissions, this may require admin privileges. If a problem is encountered on OSX/Linux, run 'sudo npm install' before using the create command. On Windows, run 'npm install' in a command line utility opened with admin privileges. +## Deploy to Emulator -- `<name>` specifies a unique name for the target. +If you wish to run a device emulator, download and install the BlackBerry 10 Simulator. -- `<ip-address>` specifies the ip address of the BlackBerry device or emulator. - -- `-t <device | simulator>` specifies the target type. If not provided, the default value is device. - -- `-p|--password <password>` specifies the password for the device or emulator. This is required only if the device or emulator is password protected. - -- `--pin <device-pin>` specifies the PIN of the BlackBerry device, which identifies that device as a valid host for the debug token. This argument is required only if you are creating a debug token. +* [Download](http://developer.blackberry.com/native/download/) +* [Getting Started](http://developer.blackberry.com/devzone/develop/simulator/blackberry_10_simulator_start.html) Before testing an app on either an emulator or a device, you need to add a _target_ to your project. Each is identified with a unique name, and associated with an IP address. You need to get the IP address from the emulator before you use it to view apps. @@ -107,43 +95,31 @@ An additional set of command-line utilities are included when you set up the Bla Windows - platforms\blackberry10\cordova\target.bat add emu 169.254.0.1 -t simulator + $ platforms\blackberry10\cordova\target.bat add emu 169.254.0.1 -t simulator -- When you build the app in release mode, you are preparing it for distribution through BlackBerry World. The script packages your app resources and plugins together in a .bar file, then signs the app. - -- When you build the app in debug mode, you are preparing it to be tested. The script packages your app resources and plugins together in a .bar file, but does not sign it. The script can also deploy the app onto a previously defined target. If you have not already created and installed a debug token, you can supply the keystore password, and the build script will create and install the debug token for you as well. +Mac/Linux - platforms/blackberry10/cordova/target add emu 169.254.0.1 -t simulator + $ platforms/blackberry10/cordova/target add emu 169.254.0.1 -t simulator Then, run the `emulate` command to view the app: - cordova emulate blackberry10 + $ cordova emulate blackberry10 ## Deploy to Device To deploy to a device, make sure it is plugged into your computer. Enable development mode and obtain the IP address as desribed in the emulator section above. You will also need to obtain the PIN from the the __Settings__ application under __About → Hardware__. -- `-k|--keystorepass <password>` specifies the password you defined when you configured your computer to sign applications. - -- `-b|--buildId <number>` specifies the build version number of your application. Typically, this number should be incremented from the previous signed version. This argument is optional. - -- `-p|--params <params-JSON-file>` specifies a JSON file containing additional parameters to pass to downstream tools. This argument is optional. + Run the target command-line utility to associate a name with an IP address, device password and PIN. Windows - platforms\blackberry10\cordova\target.bat add mydevice 169.254.0.1 -t device --password 123456 --pin FFFF972E + $ platforms\blackberry10\cordova\target.bat add mydevice 169.254.0.1 -t device --password 123456 --pin FFFF972E Mac/Linux -- `<target>` specifies the name of a previously added target. If `<target>` is not specified, the default target is used, if one has been created. This argument is only required if you want the script to deploy your app to a BlackBerry device or emulator and you have not created a default target. Additionally, if `<target>` is a device, then that device must be connected to your computer by USB connection or be connected to the same Wi-Fi network as your computer. - -- `-k|--keystorepass <password>` specifies the password you defined when you configured your computer to sign applications. This password is also used to create your debug token. This argument is only required if you want the script to create and install the debug token for you. - -- `-p|--params <params-JSON-file>` specifies a JSON file containing additional parameters to pass to downstream tools. - -- `-ll|--loglevel <level>` specifies the log level. The log level may be one of `error`, `warn`, or `verbose`. + $ platforms/blackberry10/cordova/target add mydevice 169.254.0.1 -t device --password 123456 --pin FFFF972E --password refers to the password to unlock the device @@ -151,19 +127,17 @@ Mac/Linux Then, run the `run` command to view the app: - cordova run blackberry10 + $ cordova run blackberry10 If a debug token has not yet been created for this device, an error message will prompt you to use the platform run script with the password you provided when registering for signing keys. Windows - platforms\blackberry10\cordova\run.bat --device --keystorepass mysecret + $ platforms\blackberry10\cordova\run.bat --device --keystorepass mysecret -where - -- `<target>` specifies the name of a previously added target. If `<target>` is a device, then that device must be connected to your computer by USB connection or be connected to the same Wi-Fi network as your computer. +Mac/Linux - platforms/blackberry10/cordova/run --device --keystorepass mysecret + $ platforms/blackberry10/cordova/run --device --keystorepass mysecret ## Debugging with WebInspector @@ -175,16 +149,16 @@ For more information, see [Debugging using WebInspector](http://developer.blackb ## Building a Release Version -By default, running the `cordova build` command creates an unsigned _.bar_ package file suitable for testing in a device or simulator. +By default, running the `cordova build` command creates an unsigned _.bar_ package file suitable for testing on a device or simulator. -You need to run a different `build` command to create a release version suitable for distribution through BlackBerry World. This command, also available within `platforms/blackberry10`, uses the following syntax: +You need to run a different `build` command to create a release version suitable for distribution through BlackBerry World. This command uses the following syntax: Windows - platforms\blackberry10\cordova\build.bat --release --keystorepass mysecret + $ platforms\blackberry10\cordova\build.bat --release --keystorepass mysecret Mac/Linux - platforms/blackberry10/cordova/build --release --keystorepass mysecret + $ platforms/blackberry10/cordova/build --release --keystorepass mysecret --keystorepass specifies the password you defined when you configured your computer to sign applications.
