This guide shows you how to create applications and deploy them tovarious native mobile platforms using the cordova
command-lineinterface (CLI). This tool allows you to create new projects, buildthem on different platforms, and run on real devices or withinemulators. The CLI is the main tool to use for the cross-platformworkflow described in the Overview. Otherwise you can also use theCLI to initialize project code, then switch to various platforms' SDKsand shell tools for continued development.
Prerequisites
Before running any command-line tools, you need to install SDKs foreach platform you wish to target.(See the Platform Guides for more details.)
To add support or rebuild a project for any platform, you need to runthe command-line interface from the same machine that supports theplatform's SDK. The CLI supports the following combinations:
- iOS (Mac)
- Amazon Fire OS (Mac, Linux, Windows)
- Android (Mac, Linux, Windows)
- BlackBerry 10 (Mac, Linux, Windows)
- Windows Phone 7 (Windows)
- Windows Phone 8 (Windows)
- Windows 8 (Windows)
- Firefox OS (Mac, Linux, Windows)
On the Mac, the command-line is available via the Terminalapplication. On the PC, it's available as Command Prompt underAccessories.
NOTE: For Windows-only platforms, you can still do yourdevelopment on Mac hardware by running Windows in a virtual machineenvironment or in dual-boot mode. For available options, see theWindows Phone Platform Guide or the Windows 8 Platform Guide.
The more likely it is that you run the CLI from different machines,the more it makes sense to maintain a remote source code repository,whose assets you pull down to local working directories.
Installing the Cordova CLI
The Cordova command-line tool is distributed as an npm package in aready-to-use format. It is not necessary to compile it from source.
To install the cordova
command-line tool, follow these steps:
-
Download and install Node.js. Followinginstallation, you should be able to invoke
node
andnpm
on yourcommand line. If desired, you may optionally use a tool such asnvm
ornave
to manage your Node.js installation. -
Download and install a git client, if you don'talready have one. Following installation, you should be able to invoke
git
on your command line. Even though you won't be usinggit
manually,the CLI does use it behind-the-scenes to download some assets whencreating a new project. -
Install the
cordova
module usingnpm
utility of Node.js. Thecordova
module will automatically be downloaded by thenpm
utility.-
on OS X and Linux:
$ sudo npm install -g cordova
On OS X and Linux, prefixing the
npm
command withsudo
may be necessary to install this development utility inotherwise restricted directories such as/usr/local/share
. If you are using the optionalnvm/nave tool or have write access to the install directory,you may be able to omit thesudo
prefix. There aremore tipsavailable on usingnpm
withoutsudo
, if you desire to do that. -
on Windows:
C:\>npm install -g cordova
The
-g
flag above tellsnpm
to installcordova
globally. Otherwiseit will be installed in thenode_modules
subdirectory of the currentworking directory.You may need to add the
npm
directory to yourPATH
in order to invokeglobally installednpm
modules. On Windows,npm
can usually be found atC:\Users\username\AppData\Roaming\npm
. On OS X and Linux it can usuallybe found at/usr/local/share/npm
.The installation log may produce errors for any uninstalledplatform SDKs.
Following installation, you should be able to run
cordova
on the command line with no arguments and it shouldprint help text. -
Create the App
Go to the directory where you maintain your source code, and run acommand such as the following:
$ cordova create hello com.example.hello HelloWorld
It may take some time for the command to complete, so be patient. Runningthe command with the -d
option displays information about its progress.
The first argument hello specifies a directory to be generatedfor your project. This directory should not already exist, Cordova willcreate it for you. Its www
subdirectory houses your application'shome page, along with various resources under css
, js
, and img
,which follow common web development file-naming conventions. Theconfig.xml
file contains important metadata needed to generate anddistribute the application.
The second argument com.example.hello
provides your project with a reverse domain-style identifier. This argumentis optional, but only if you also omit the third argument, since the argumentsare positional. You can editthis value later in the config.xml
file, but do be aware that there maybe code generated outside of config.x