3. Installing the Cordova Command-Line Interface
To make it easier for developers to manage their projects, the Cordova project team built a single, unified command-line interface (CLI) that is expected to eventually work across all of the Cordova-supported mobile device platforms. This chapter illustrates how to install the Cordova CLI. The following chapter shows you how to use it to manage your Cordova projects.
The PhoneGap CLI is essentially the Cordova CLI with some additional commands added on. Almost everything you learn in this chapter easily applies to the PhoneGap CLI as well. You should refer to the PhoneGap documentation at http://docs.phonegap.com/en/3.0.0/index.html for information about the additional commands the PhoneGap CLI adds.
Installing the CLI
The Cordova CLI is built using JavaScript code that is exposed through the Node JavaScript runtime engine (www.nodejs.org). Because it is built using JavaScript, it can essentially run anywhere that Node.js is available (Linux, Macintosh OS X, and Microsoft Windows). The instructions that follow will help you get the CLI installed on your development workstation; there are separate instructions for Macintosh OS X and Microsoft Windows; I won’t be covering the Linux install.
Note
The CLI is a brand new feature for Cordova, so it’s a little finicky about your development system’s configuration. Be sure to follow all of the steps in the CLI readme.md. In the sections that follow, I show you all of the steps I had to complete to get this to work on my Macintosh and Windows systems. In your environment, you may or may not need to follow these steps.
Be prepared to update all of your mobile SDKs and development tools, and be sure to follow all of the instructions. Be prepared to be patient because the CLI has a lot of required libraries that must be installed with it.
The CLI has to be able to create new Cordova projects, so it provides the necessary project files, plus it has to interface with the native SDKs to build projects and load applications in an emulator or simulator. Therefore, you have to make sure that the appropriate SDKs are installed (depending on which platforms you’re working with) and that the SDKs are visible to the CLI. For BlackBerry, iOS, and Windows, for example, the SDKs are installed on the system, so the CLI can easily find what it needs. For Android, there is no installer, so you have to manually configure your system so the CLI can find the SDK and associated tools.
In the sections that follow, I show you how to install the appropriate tools for Android, BlackBerry 10, iOS, and Windows Phone required to use the Cordova CLI on Microsoft Windows and Mac OS X. Chapters 7 through 10 show you in detail how to use the platform-specific capabilities for the different mobile OSs listed. So, if you’re going to do some Cordova development for a particular mobile OS, read through the instructions here, then take a look at the appropriate chapter for your particular OS (Chapter 7 for Android, Chapter 8 for BlackBerry 10, Chapter 9 for iOS, and Chapter 10 for Windows Phone 8).
Android Development Tools
One of the requirements for the Android SDK is the Java Development Kit (JDK). On Macintosh, you should have Java already available, although you may have to install it first. Open a terminal window and type javac at the command prompt, and press Enter. If you see a bunch of help text scroll by, you’re all set. If not, you’ll see instructions on how to download and install the appropriate Java files for your system.
On Windows, you need to point your browser of choice to http://java.oracle.com and download the JDK. On the Java home page, select Java SE, then download and install the latest version of the JDK.
At the conclusion of the JDK installation, there’s still one more step to complete: you need to define the JAVA_HOME environment variable and point it to where the JDK is installed. To create the JAVA_HOME environment variable, assuming you’re running Windows 7, right-click on the Computer icon (it used to be called My Computer in older versions of Windows), then select Properties. On the dialog that appears, select Advanced system settings, as highlighted on the left side of Figure 3.1.
In the dialog that appears, select the Advanced tab, as shown in Figure 3.2, and click the Environment Variables... button highlighted in the figure.
In the dialog that appears, click the New button to add a user variable called JAVA_HOME that points to where the JDK software is located, as shown in Figure 3.3.
To test the configuration, save your changes, open a new terminal window and type set, then press Enter. You should see a long list of environment variables; look for an entry for your new JAVA_HOME variable.
With Java installed and configured, it’s time to install the Android SDK. Open your browser of choice and point it to http://developers.android.com. On the Android developer home page, follow the links to download the Android SDK; on the current site, it is labeled “Get the SDK.”
There is no installer for the SDK; it ships as a .zip file, so after it downloads, you have to extract the files to a location that makes sense for you. On Macintosh OS X, when you download .zip files using the Safari browser, the files are automatically extracted to the Downloads folder for you. Some developers might drag the extracted folder to the /Applications folder, but on my system I simply left everything in Downloads.
The SDK download includes the tools you need to build and emulate Android applications, including a preconfigured version of Eclipse, but does not contain all of the SDK libraries and device emulators you might need for your applications. There are additional steps you need to follow to download the SDK libraries and device emulators you will need—follow the instructions located at http://developer.android.com/sdk/installing/bundle.html to complete this step.
Because there’s no installer for the Android SDK, the CLI won’t know where to find Android SDK tools, so you have to add some folders to the system path. Specifically, the CLI needs to know where to find the SDK platform-tools and tools folders.
On Macintosh, there are several ways to update the system path; for my installation, I used TextMate to modify the paths file by issuing the following command:
mate /etc/paths
Figure 3.4 shows the file open in the editor. I left the existing file contents alone and the file paths for the platform-tools and tools folders to the file as separate lines.
On Windows, you can access the settings you need from the Control Panel. The easiest way to get there is to right-click on the Computer icon in the Start Menu then select Properties. In the window that appears, select Advanced system settings, as shown in Figure 3.1. In the Environment Variables dialog, select the PATH variable and click the Edit button, or simply double-click on the PATH entry. Append the folder paths for the Android SDK platform-tools and tools folders to the existing path environment variable, placing a semicolon between each entry, as shown in Figure 3.5.
After saving your changes, you should be able to open a terminal window and type android to run the Android SDK Manager, as shown in Figure 3.6. The SDK Manager should look the same regardless of whether you’re running on Macintosh OS or Windows.
If you added the two required paths to the system path and the SDK Manager doesn’t load when you type android at a command prompt, then the configuration is incomplete and the CLI will not be able to manipulate Android projects. You’ll need to go back and resolve any issues before continuing.
If you know you will need to develop Cordova applications for Android OS versions beyond the default ones installed with the Android SDK Manager, now might be a good time to select the required additional platforms and install those as well.
You can read more about Android development for Apache Cordova in Chapter 7, “Android Development with Cordova.”
BlackBerry Development Tools
To build Cordova applications for BlackBerry, you must register for and install a set of encryption keys used to sign BlackBerry applications. A BlackBerry application will run in a BlackBerry simulator but must be signed before it will run on a physical device. To register for a set of keys, point your browser of choice to https://www.blackberry.com/SignedKeys/codesigning.html and follow the instructions. The good news is that signing keys are free and can be obtained in 1 to 2 hours. After you request the keys, you will receive several emails with instructions on how to configure your development environment for them. I describe how to register and use the signing keys in Chapter 8, “BlackBerry 10 Development with Cordova.”
For Cordova 3, you will use the BlackBerry Native SDK (NSDK) to build Cordova applications. Older versions of Cordova used the BlackBerry WebWorks SDK, but they’ve switched over to the NSDK. It’s possible that by the time you read this that there will be a smaller, command-line tools installation you can use for Cordova development. Be sure to check the readme at https://github.com/apache/cordova-cli to make sure of the latest requirements before continuing.
Note
Cordova 3.0 and higher support development on BlackBerry 10 and the BlackBerry PlayBook device platforms. Beginning with Cordova 3.0, support for BlackBerry 7 devices has been dropped, so if you want to develop for older BlackBerry devices, you need to use Cordova 2.9 or earlier.
To install the NSDK, point your browser to http://developer.blackberry.com/native and follow the instructions to download and install the appropriate software depending on whether you will be developing for BlackBerry 10 or the BlackBerry PlayBook platform. The NSDK installation requires that you execute a script or batch file (depending on whether you’re running on Macintosh OS X or Windows) to properly configure the system environment for command-line use. Be sure to follow the complete installation instructions on the BlackBerry Developers website. If you don’t complete this step, you may see the following error during installation of the CLI:
WARNING: Your system does not meet requirements to create blackberry projects. See error
output below.
The BB10NDK environment variable QNX_HOST is missing. Make sure you run `source <path to
bb10ndk>/bbndk-env.sh`. Even better, add `source`ing that script to your .bash_profile or
equivalent so you don't have to do it manually every time.
SKIPPING blackberry bootstrap.
The BlackBerry device simulators for BlackBerry 10 and the PlayBook use a VMWare virtual machine for the simulators. For Macintosh installations, you need to acquire and install a VMWare Fusion (www.vmware.com/products/fusion/overview.html) license before you can install the simulators. For Windows, you can use the free VMWare player application, which is available at www.vmware.com/products/player. Simply install the player application then install the BlackBerry 10 device simulator software.
You can read more about BlackBerry 10 development for Apache Cordova in Chapter 8.
iOS Development Tools
Before you can do much around iOS development, you must join the Apple iOS Developer program. You can find information about the program at https://developer.apple.com/programs/ios; there’s a yearly fee and different capabilities available to you depending on which program you choose.
Next, you want to open the Macintosh App Store, search for “xcode,” and install the Xcode IDE, as shown in Figure 3.7.
Xcode is a huge install, so find something else to do for a while as it downloads. Once the installation has completed, you need to launch Xcode and install Xcode command-line tools. With Xcode open, open the Xcode menu and select Preferences. In the dialog that appears, select Downloads, then the Components tab, shown in Figure 3.8.
If you have the command-line tools installed as shown in Figure 3.8, you’re all set. If not, there will be a button on the far right you can click to complete the installation. This is another large download, so be prepared for this to take a while. With that complete, you’re still not done: there are a few more steps to complete for your Xcode configuration.
The Xcode command-line tools have their own license agreement that you must agree to before they can be used. You can’t agree to the terms during installation; instead you must open a Macintosh Terminal window and execute the following command:
xcodebuild -license
If you receive an error, then the Xcode command line hasn’t been installed correctly, and you’ll have to go back and resolve the problem before continuing. If installed correctly, you should see a screen similar to the one shown in Figure 3.9.
Press the space bar repeatedly until you have read the entire agreement. When you reach the end of the agreement, you will see a screen similar to the one shown in Figure 3.10. If you agree with the terms of the agreement, type the word “agree” and press the Enter key. If you don’t, then you will not be able to use the Xcode command-line tools, and the Cordova CLI will not work for iOS development on the system—sorry.
If you skip this process, during the installation of the Cordova CLI, you will receive the error message shown in Figure 3.11.
If you intend to use the CLI to build and test Cordova applications, you may have one last step to complete first. At this stage of the installation process, if you attempted to test a Cordova application on iOS using the CLI, you may get the following error:
[Error: An error occurred while emulating/deploying the ios project.Error: ios-sim was not
found. Please download, build and install version 1.5 or greater from
https://github.com/phonegap/ios-sim into your path. Or 'brew install ios-sim' using
homebrew: http://mxcl.github.com/homebrew/
This happens because the tools needed for the CLI to launch the iOS simulator aren’t (currently) included with the Cordova download or the CLI, so you have to install them manually. The error message provides you with two options. I didn’t have Homebrew installed, so I chose to install directly from Github. I downloaded the project files from https://github.com/phonegap/ios-sim, opened a Terminal window, navigated to the folder where I’d extracted the ios-sim download, then issued the following command in the terminal:
rake install prefix=/usr/local/
The command will build the tool and install it in a place where it can be easily accessed by the CLI.
You can read more about iOS development for Apache Cordova in Chapter 9, “iOS Development with Cordova.”
Windows Phone Development Tools
If you will be doing Windows Phone development for Cordova, you first need a system running Microsoft Windows (the development tools won’t run on Linux or Macintosh OS X), plus you need to install the Microsoft Windows Phone SDK. You can download the SDK from the Windows Phone Dev Center located at http://developer.windowsphone.com. You can use version 8 of the SDK for both Windows Phone 8 and Windows Phone 7.5 applications, so if you’re developing for those two OSs, you have all you need in that version. Windows Phone applications are built using Visual Studio, and there’s a free Visual Studio Express download available in the dev center. For Windows Phone 8 applications, you need to install Visual Studio Express 2012, which is included with the SDK. After you install the SDK, you need to register with Microsoft for a free license key for Visual Studio Express.
The Windows Phone development tools have some hefty system requirements, so be sure to check out the requirements for the particular version of Visual Studio you will be using for your Cordova development and make sure your system exceeds the minimum requirements. Failure to do so will cause some stress, as the system will not be as responsive as you may expect.
Warning
The Windows Phone emulators place a pretty big load on the system running them. Microsoft has enhanced the tools to help reduce the system requirements, but when you launch an emulator for the first time, you’ll get warnings for some system BIOS settings you need to change to enhance performance.
When I wrote PhoneGap Essentials, I found that I couldn’t even run the emulators in a VMWare virtual machine, even on the most modern and fastest system I had. For this book, I decided to upgrade one of my lab systems, install Windows 8, and dedicate it to Windows Phone development so I wouldn’t have to deal with potential performance issues.
You can read more about Windows Phone 8 development for Apache Cordova in Chapter 10, “Windows Phone 8 Development with Cordova.”
CLI Installation
The CLI is written in JavaScript and therefore uses Node.js as a runtime execution engine. The CLI currently requires Node.js 0.10 and higher, so if you already have it installed, make sure you update it to the latest version. To install Node.js, point your browser of choice to www.nodejs.org, then download and install the software. Node.js will install in your system path, so you can open a terminal window and type node to launch the Node.js application.
During installation, the CLI retrieves some code from GitHub (www.github.com), so you will need to have Git installed on your development workstation. If you’re running on Linux or Macintosh OS X, you can install Git using the Node.js package manager (npm) by opening a terminal window and typing:
npm install –g git
On Windows, you will have to download Git tools and install them on your development workstation from http://git-scm.com.
Once you’ve completed the installation, open a terminal window (Mac OS X) or command prompt (Windows), type git, and press Enter. A bunch of text should scroll by, and then you should see a screen similar to the one shown in Figure 3.12.
If you receive an error message indicating that the git command couldn’t be found, then the Git installation didn’t complete successfully, and you will need to resolve the error before continuing.
With Git and Node.js installed, you’re ready to install the Cordova CLI; to install the CLI, you have two options.
If you downloaded the Cordova framework from the Cordova website (described in Chapter 2), you can navigate to the folder that contains the framework files and extract the contents of the cordova-cli.zip file. Once the files are extracted, open a terminal window and navigate to the folder that contains the extracted files, then issue the following command:
npm install
The other option is to pull the latest version of the CLI from the Internet using npm. On Windows, open a command prompt and issue the following command:
npm install –g cordova
The –g in the command tells npm to install the Cordova CLI globally—if you did not use this parameter, the CLI would be available only from the current folder.
On Macintosh, you must do more to complete the installation. The previous command may work, but if you receive the EACCESS error shown in Figure 3.13, you will have to try a different approach.
To get around this error, you need to install Cordova with sudo by using the following command:
sudo npm install –g cordova
Sudo allows you to execute programs with a higher access level, so when you issue the command, you should be prompted for your password before the installation begins.
The CLI installation installs a ton of stuff, so be prepared to watch a lot of information go scrolling by. When it is all done, you will see a message summarizing what was installed; if you scroll back up through the listing, you will see how much stuff was installed during the process.
In my experience with the CLI, a lot can go wrong with the installation, but you won’t be able to tell because it will seem to have installed correctly. To remedy this, you should scroll back through the entire installation history shown in the terminal and look for errors.
That’s it—that’s all there is to installing the Cordova CLI. To test the installation, open a terminal window, type cordova at the prompt, and press Enter. If everything installed correctly, you should see a screen similar to the one shown in Figure 3.14.
If you’re interested in using the PhoneGap CLI, it installs basically the same way; you can install from the Internet using the following command:
npm install –g phonegap
The PhoneGap CLI will likely be a bit behind the Cordova CLI, so don’t expect the two to be at the same version number or to have all of the same features. Features are typically flushed out in the Cordova CLI, then migrated into the PhoneGap CLI later.
Wrap-Up
In this chapter, I showed you how to install the Cordova CLI on Windows and Macintosh OS X. With these tools in place, you’re ready to begin writing your own Cordova applications. In the next chapter, I show you how to use the CLI to manage your Cordova projects.