license: > Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Cordova now ships with a set of command-line tools that make it easier for you to develop cross-platform applications. You can build, clean, and launch an emulator with a single command. You can consider these instructions as an alternative to the Getting Started guides. Whereas the Getting Started guides help you get setup with the default IDEs and tooling surrounding the platforms you are working with, the command-line tools aim to provide a shell-based approach to creating and working with Cordova projects.
The Windows Phone command line tools support creating, building and running new projects. Commands must be run from a cmd or powershell prompt.
Run the create
command with the following parameters:
$ C:\path\to\cordova-wp8\bin\create C:\path\to\my_new_cordova_project com.example.cordova_project_name CordovaProjectName
$ C:\path\to\my_new_cordova_project\cordova\build --debug
$ C:\path\to\my_new_cordova_project\cordova\build --release
Run the ‘run’ command with the following optional parameters
--emulator
, --device
, or --target=<targetID>
.--debug
, --release
, or --nobuild
.$ C:\path\to\my_new_cordova_project\cordova\run [Target] [Build]
By default the run
command will look for a connected device, if no device is found it will look for any started emulators. If you have multiple emulators, you can specify a target ID.
$ C:\path\to\my_new_cordova_project\cordova\clean
The iOS command-line tools are built upon shell scripts and rely on Xcode command-line tools such as xcode-select
and xcodebuild
.
Run the create
command with the following parameters:
$ ./path/to/cordova-ios/bin/create /path/to/my_new_cordova_project com.example.cordova_project_name CordovaProjectName
$ /path/to/my_new_cordova_project/cordova/build
$ /path/to/my_new_cordova_project/cordova/run
$ /path/to/my_new_cordova_project/cordova/release
$ /path/to/my_new_cordova_project/cordova/log
The Android command-line tools are built upon shell scripts. You must have the Android SDK's tools
and platform-tools
folders in your PATH!
Run the create
command with the following parameters:
$ /path/to/cordova-android/bin/create /path/to/my_new_cordova_project com.example.cordova_project_name CordovaProjectName
or, on Windows
$ C:\path\to\cordova-android\bin\create.bat C:\path\to\my_new_cordova_project com.example.cordova_project_name CordovaProjectName
$ /path/to/my_new_cordova_project/cordova/build --debug
or, on Windows
$ C:\path\to\my_new_cordova_project\cordova\build.bat --debug
$ /path/to/my_new_cordova_project/cordova/build --release
or, on Windows
$ C:\path\to\my_new_cordova_project\cordova\build.bat --release
Run the ‘run’ command with the following optional parameters
--emulator
, --device
, or --target=<targetID>
.--debug
, --release
, or --nobuild
.$ /path/to/my_new_cordova_project/cordova/run [Target] [Build]
or, on Windows
$ C:\path\to\my_new_cordova_project\cordova\run.bat [Target] [Build]
Make sure you have created at least one Android Virtual Device. If you did not it will ask you to create one with the android
command. By default the run
command will look for a connected device, if no device is found it will look for any started emulators. If you have multiple AVDs, you can specify a target ID.
$ /path/to/my_new_cordova_project/cordova/log
or, on Windows
$ C:\path\to\my_new_cordova_project\cordova\log.bat
$ /path/to/my_new_cordova_project/cordova/clean
or, on Windows
$ C:\path\to\my_new_cordova_project\cordova\clean.bat
The BlackBerry command-line tools are built upon shell scripts.
Run the create
command with the following parameters:
$ /path/to/cordova-blackberry-webworks/bin/create /path/to/my_new_cordova_project com.example.cordova_project_name CordovaProjectName
or, on Windows
$ /path/to/cordova-blackberry-webworks/bin/create.bat /path/to/my_new_cordova_project com.example.cordova_project_name CordovaProjectName
Note: the package name placeholder (com.example.cordova_project_name) is ignored on the BlackBerry platform, but is required for use of the crossplatform tools
For BlackBerry projects, please make sure you customize the project.properties
file in the root of your Cordova project folder. This is necessary for things like supplying your BlackBerry signing key password, location of the BlackBerry WebWorks SDK, and location of BlackBerry simulator executables.
$ /path/to/my_new_cordova_project/cordova/build <platform>
or, on Windows
$ /path/to/my_new_cordova_project/cordova/build.bat <platform>
For BlackBerry projects, please make sure you customize the project.properties
file in the root of your Cordova project folder. This is necessary for things like supplying your BlackBerry signing key password, location of the BlackBerry WebWorks SDK, and location of BlackBerry simulator executables.
$ /path/to/my_new_cordova_project/cordova/run <platform>
and then choose ‘no’ when prompted with:
Do you have a BlackBerry device connected to your computer? (y/n)
or, on Windows
$ /path/to/my_new_cordova_project/cordova/run <platform>
and then choose ‘no’ when prompted with:
Do you have a BlackBerry device connected to your computer? (y/n)
Unfortunately streaming logs directly from the device is not supported at this time. However, BlackBerry offers built-in Web Inspector support for Playbook and BlackBerry smartphone devices running BlackBerry OS 7.0 and above. Additionally, you can access your application's logs (including any calls to console.log
) on your device by holding down the ALT key from the home screen and hitting “lglg” keys.
Command-line tools are based on shell scripts. If you need help with a command, type the command with the -h
or -help
arguments, which are supported by all commands and which will provide descriptions for each of the available arguments.
The following commands are available:
The ‘create’ command creates a new project:
bin/create <path-to-project>
The target
command allows you to manage the BlackBerry device(s) or simulator that you will use to test your app. You can add or remove a target, or set a target as the default target.
<path-to-project>/cordova/target add <name> <ip-address> <device | simulator> [-p | --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 simulator.-p|--password <password>
specifies the password for the device or simulator. This is required only if the device or simulator 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.<path-to-project>/cordova/target remove <name>
<path-to-project>/cordova/target default <name>
The build
command builds the project as a .bar file. You can build your app in either release mode (which produces a signed .bar file) or in debug mode (which produces an unsigned .bar file).
<path-to-project>/cordova/build release -k|--keystorepass <password> [-b|--buildId <number>] [-p|--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.<path-to-project>/cordova/build debug [<target>] [-k|--keystorepass <password>] [-p|--params <params-JSON-file>] [-ll|--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 simulator 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
.If you have previously defined a default target (and previously 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:
<path-to-project>/cordova/build debug
The run
command deploys the app on the specified BlackBerry device or a simulator. Before deploying your app, you must first create a target for the device or simulator you want to deploy your app to. The deploy script will deploy the most recent build of your app.
<path-to-project>/cordova/run <target>
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.The target
command allows you to add and remove plugins
<path-to-project>/cordova/plugin fetch <path-to-plugin>
<path-to-project>/cordova/plugin ls
<path-to-project>/cordova/plugin add <name>
<path-to-project>/cordova/plugin rm <name>
The Windows 8 command line tools support creating new projects only. Commands must be run from a cmd or powershell prompt.
Run the create
command with the following parameters: