Repository: cordova-blackberry Updated Branches: refs/heads/master cf350f02b -> a5328c6a3
CB-6222 Various updates for the BlackBerry 10 documentation Markdown README Document build --web-inspector and --no-signing Document release <target> Document --query Reference BlackBerry 10 instead of BlackBerry Update bin/create documentation Add Conventions section referencing Windows \\ v. / Remove --shortforms Remove keystorepass flag Remove target default documentation Remove --keystore pass from documentation `build debug` Fix jake hint warnings Fix debug mode copy-paste error Project: http://git-wip-us.apache.org/repos/asf/cordova-blackberry/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-blackberry/commit/a5328c6a Tree: http://git-wip-us.apache.org/repos/asf/cordova-blackberry/tree/a5328c6a Diff: http://git-wip-us.apache.org/repos/asf/cordova-blackberry/diff/a5328c6a Branch: refs/heads/master Commit: a5328c6a34c1023573b086e87dbfb4e79b93ef75 Parents: cf350f0 Author: Josh Soref <[email protected]> Authored: Mon Feb 10 12:32:18 2014 -0500 Committer: Josh Soref <[email protected]> Committed: Tue Mar 11 14:22:00 2014 -0400 ---------------------------------------------------------------------- blackberry10/README.md | 82 ++++++++++---------- .../templates/project/cordova/lib/run-utils.js | 2 +- .../bin/templates/project/cordova/lib/run.js | 2 +- 3 files changed, 43 insertions(+), 43 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-blackberry/blob/a5328c6a/blackberry10/README.md ---------------------------------------------------------------------- diff --git a/blackberry10/README.md b/blackberry10/README.md index bb3abfa..f172719 100644 --- a/blackberry10/README.md +++ b/blackberry10/README.md @@ -1,25 +1,29 @@ Apache Cordova for BlackBerry 10 ================================ -Apache Cordova is an application development platform that allows you to use common web technologies, primarily HTML5, JavaScript, and CSS, to create applications for mobile devices. Cordova uses a standard set of APIs to access common device features. Additional plugins allow you to access BlackBerry specific APIs, so that you can extend your application to tightly integrate with the BlackBerry 10 OS. +**Apache Cordova** is an application development platform that allows you to use common web technologies, primarily **HTML5**, **JavaScript**, and **CSS**, to create applications for mobile devices. **Cordova** uses a standard set of APIs to access common device features. Additional plugins allow you to access **BlackBerry 10** specific APIs, so that you can extend your application to tightly integrate with the **BlackBerry 10 OS**. Requirements ------------ -Cordova for BlackBerry has the following software requirements: +Cordova for BlackBerry 10 has the following software requirements: -- 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/) +- **Windows XP** (32-bit), **Windows 7** (32-bit and 64-bit), or **Mac OS X** 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/) - After installing the 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: - - [Linux/Mac] source [BBNDK directory]/bbndk-env.sh - - [Windows] [BBNDK directory]\bbndk-env.bat + After installing the 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: + - *Linux/OS X* `source [BBNDK directory]/bbndk-env.sh` + - *Windows* `[BBNDK directory]\bbndk-env.bat` + +Conventions +----------- +The instructions in this document will generally use `/` as the path separator. On *Windows*, you should enter `\` where you see `/` in these instructions. Setting up your signing keys ---------------------------- -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. +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. - [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) @@ -33,37 +37,38 @@ To create a new project, you use the `create` command to set up the folder struc 1. On the command line, navigate to the folder where you extracted Cordova. 2. Run the `create` command using the following syntax: - bin/create <path-to-project> <project-package> <project-name> + bin/create <path-to-project> [<project-package> [<project-name> [<path-to-www-template>]]] -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. +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. where -- '<path-to-project>' specifies the directory you want the project created in -- '<project-package>' specifies a reverse domain style identifier -- '<project-name>' specifies the apps display name +- `<path-to-project>` specifies the directory to create for your project +- `<project-package>` specifies a reverse domain style identifier +- `<project-name>` specifies the app's display name +- `<path-to-www-template>` specifies the directory to use as a template -*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. +*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 *OS X*/*Linux*, run `sudo npm install` before using the `create` command. On *Windows*, run `npm install` in a command line utility opened with admin privileges. Adding and managing targets --------------------------- -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. +A target refers to a **BlackBerry 10** *device* or *simulator* 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. ###Add a target To add a target, on the command line, type the following command: - <path-to-project>/cordova/target add <name> <ip-address> [-t | --type <device | simulator>] [-p | --password <password>] [--pin <device-pin>] + <path-to-project>/cordova/target add <name> <ip-address> [--type simulator] [--password <password>] [--pin <device-pin>] where - `<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. +- `<ip-address>` specifies the ip address of the **BlackBerry 10** *device* or *simulator*. +- `--type simulator` If not provided, *device* is assumed. +- `--password <password>` specifies the password for the *device*/*simulator*. This is only necessary if the *device*/*simulator* is password protected. +- `--pin <device-pin>` specifies the `PIN` of the **BlackBerry 10** *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*. ###Remove a target @@ -71,46 +76,41 @@ To remove a target, on the command line, type the following command: <path-to-project>/cordova/target remove <name> -###Set a target as the default - -To specify a specific target as the default, on the command line, type the following command: - - <path-to-project>/cordova/target default <name> - Building your app ----------------- -To build your app, run the build script. You can build the app in either release mode or in debug mode. +To build your app, run the `build` script. You can build the app in either *release mode* or in *debug mode*. -- 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. +- 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. - 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). + *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). ###Build your app in release mode To build your app in release mode, on the command line, type the following command: - <path-to-project>/cordova/build release -k|--keystorepass <password> [-b|--buildId <number>] [-p|--params <params-JSON-file>] + <path-to-project>/cordova/build release [<target>] <--query | --keystorepass <password>> [--buildId <number>] [--params <params-JSON-file>] where -- `-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. +- `<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. +- `--query` will cause you to be prompted for your keystore password +- `--keystorepass <password>` specifies the password you defined when you configured your computer to sign applications. +- `--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. +- `--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 -To build your app in release mode, on the command line, type the following command: +To build your app in debug mode, on the command line, type the following command: - <path-to-project>/cordova/build debug [<target>] [-k|--keystorepass <password>] [-p|--params <params-JSON-file>] [-l|--loglevel <error|warn|verbose>] + <path-to-project>/cordova/build debug [<target>] [--params <params-JSON-file>] [--loglevel <error|warn|verbose>] where - `<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. -- `-l|--loglevel <level>` specifies the log level. The log level may be one of `error`, `warn`, or `verbose`. +- `--params <params-JSON-file>` specifies a JSON file containing additional parameters to pass to downstream tools. +- `--loglevel <level>` specifies the log level. The log level may be one of `error`, `warn`, or `verbose`. 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: http://git-wip-us.apache.org/repos/asf/cordova-blackberry/blob/a5328c6a/blackberry10/bin/templates/project/cordova/lib/run-utils.js ---------------------------------------------------------------------- diff --git a/blackberry10/bin/templates/project/cordova/lib/run-utils.js b/blackberry10/bin/templates/project/cordova/lib/run-utils.js index ff745f2..aa91ecd 100644 --- a/blackberry10/bin/templates/project/cordova/lib/run-utils.js +++ b/blackberry10/bin/templates/project/cordova/lib/run-utils.js @@ -273,7 +273,7 @@ _self = { if (fs.existsSync(barPath)) { allDone(null, deployTarget); } else { - allDone("No build file exists, please run: build [--debug | --release] [-k | --keystorepass] [-b | --buildId <number>] [-p | --params <json>] [-l | --loglevel <level>] "); + allDone("No build file exists, please run: build [--debug | --release] [--keystorepass <password>] [--buildId <number>] [--params <json>] [--loglevel <level>] [--web-inspector] [--no-signing]"); } }, http://git-wip-us.apache.org/repos/asf/cordova-blackberry/blob/a5328c6a/blackberry10/bin/templates/project/cordova/lib/run.js ---------------------------------------------------------------------- diff --git a/blackberry10/bin/templates/project/cordova/lib/run.js b/blackberry10/bin/templates/project/cordova/lib/run.js index 48f1f91..acb3fa6 100755 --- a/blackberry10/bin/templates/project/cordova/lib/run.js +++ b/blackberry10/bin/templates/project/cordova/lib/run.js @@ -52,7 +52,7 @@ options .option('--query', 'query on the commandline when a password is needed') .option('--no-launch', 'do not launch the application on device') .option('--no-build', 'deploy the pre-built bar file and skip building') - .on('--help', function() { + .on('--help', function () { console.log(' Examples:'); console.log(''); console.log(" Deploying to a predefined target");
