3. Configuring a Cordova Development Environment

To make it easier for developers to manage their projects, the Cordova project team built a single, unified command-line interface (CLI) that works across all of the Cordova supported mobile device platforms. This chapter illustrates how to install the Cordova CLI. The following chapter will show you how to use it to manage your Cordova projects.

The PhoneGap CLI is essentially the Cordova CLI with some additional commands added on. Most everything you learn in this chapter easily applies to the PhoneGap CLI as well. In Chapter 13, “Using the PhoneGap CLI,” I describe the additional capabilities provided by the PhoneGap CLI.

The instructions provided in this chapter cover both the Microsoft Windows and Macintosh OS X operating systems. The instructions for Ubuntu are completely different, so I cover them in Chapter 10, “Ubuntu Development with Cordova.” The Windows examples I show here are for Windows 8, but the Windows 7 steps are almost identical. Later in the book I have dedicated chapters covering the tooling for Android, Firefox OS, iOS, Ubuntu, and Windows Cordova development, but both Android and iOS have some prerequisites for the CLI to operate properly, so I include the necessary information here. So, if you’re going to do some Cordova development for a particular mobile OS beyond Android and iOS, read through the instructions here, and then also take a look at the appropriate chapter for your particular OS.

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. Because of that, 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. As mentioned in the previous section, I’m going to include some up-front information on the installation of the Android and iOS SDKs so you’ll leave this chapter with fully functioning development environments for the two most popular mobile platforms.

On Windows, you will need to point your browser of choice to http://java.oracle.com and download the JDK. On the Java home page, select Java SE, and then download and install the latest version of the JDK. You will want to install a version of the Oracle JDK that matches the processor and Windows version running on your system. Install the 64-bit version of Java if you’re running a 64-bit version of Windows and a 32-bit version if you’re running a 32-bit version of Windows.

At the conclusion of the JDK installation, there are still a couple more steps to complete—you will need to define the JAVA_HOME environment variable and point it to where the JDK is installed. To create the JAVA_HOME environment variable on Windows 7, open Windows Explorer, right-click on the Computer icon (it used to be called My Computer in older versions of Windows), then select Properties. On Windows 8, open Windows Explorer, right-click on This PC (highlighted in Figure 3.1), and then select Properties.

In the dialog that appears, select Advanced system settings as highlighted on the left side of Figure 3.2.

In the dialog that appears, select the Advanced tab as highlighted in the top of Figure 3.3, then click the Environment Variables button highlighted at the bottom of the dialog.

In the dialog that appears, look for a user variable entry labeled JAVA_HOME; if there’s already one there, you can skip this step. If not, click the New button highlighted in Figure 3.4.

In the New User Variable dialog that appears, type JAVA_HOME into the Variable name field, then populate the Variable value field with the full path pointing to the JDK installation folder as shown in Figure 3.5. Click the OK button when you’re done.

On Macintosh, the Java installation automatically configures the system so you can execute Java commands from the command line, so there is no need to update the system path.

On Windows, we need to configure the system so the Java compiler is available to the command-line tools. The JDK installation doesn’t update the Windows system path, so you will have to do it manually. In the dialog shown in Figure 3.4, select the PATH variable at the top of the User variables list, then click the Edit button.

Figure 3.6 shows the dialog that appears. In the Variable value field, add a semicolon at the end of the existing value, then append %JAVA_HOME%in to the field as shown in the figure. This tells Windows to look for executables in the bin folder underneath the folder name described in the JAVA_HOME variable. So, in this example, I’m essentially adding C:Program FilesJavajdk1.8.0_11in to the path.

When you’re finished, click the series of OK buttons to take you back to the Control Panel. To test the configuration, 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.

Next, type javac in the terminal window and press the Enter key. You should see information about the available Java Compiler commands scroll past on the screen. If you do, the PATH variable is configured correctly. If you receive an error message, there is an error in the PATH variable configuration that you will have to resolve before continuing.

There’s not much to installing Ant. The project doesn’t include an installer; all you need to do is download the latest distribution, unpack the files to an appropriate destination, then modify the system path so that applications, like the Cordova CLI, can execute it. What I typically do is extract the files into the system’s Downloads folder, rename the extracted folder to ant, then move the files to an appropriate destination. On Windows I move the folder to the root of my system’s primary hard drive (usually C:) so the Ant files will be found at C:ant. On Macintosh, I usually drag the files into the system’s Applications folder. An example of the Ant installation on my Windows 8 system is shown in Figure 3.7.

Macintosh users can also install Ant using Homebrew (http://brew.sh). When you install Ant using Homebrew, the system path is updated automatically, so you can skip the following instructions.

The Cordova and Android command-line tools need to be able to execute Ant from any folder, so you will need to update the system path with the Ant installation’s bin folder.

On Windows 7, open Windows Explorer, then right-click on the Computer icon (it used to be called My Computer in older versions of Windows) and select Properties. On Windows 8, open Windows Explorer and right-click on This PC (highlighted in Figure 3.1), then select Properties. In the dialog that appears (shown in Figure 3.4), select the PATH variable at the top of the User variables list, then click the Edit button.

Append a semicolon and the path to the Ant installation’s bin folder to the Variable value field in the dialog as shown in Figure 3.8. Click the OK button to save your changes.

On Macintosh, there are several ways to update the system path. The easiest way I’ve found is to simply use a text editor to open the system’s bash profile and make some changes there. To do this, open a terminal window and invoke the default text editor using the following command:

open ~/.bash_profile

Within the file, add the following lines after the existing content in the file:

Click here to view code image

ANT_HOME=/Applications/ant
PATH=$PATH:$HOME/bin:$ANT_HOME/bin
export ANT_HOME PATH

Remember, I dragged the ant folder to the system’s Applications folder; if you placed your Ant files in a different location, be sure to update the value associated with the ANT_HOME variable in the example with the correct location. Save the changes, then exit the editor. To test the configuration, from a terminal window execute the following command:

ant

If Ant is installed correctly, you should see a response similar to the one shown in Figure 3.9.

This is not an error; it’s simply Ant’s way of telling you that it did not find the configuration file it needed in the current folder. This is OK as we’ve not created any projects yet, so the build file we need isn’t there (yet)—the Cordova CLI will add it for us later. If you’re in a folder that contains a build.xml file, when you execute the command you will see a bunch more text outputted to the screen as Ant reads the build.xml file and starts following the instructions in the file.

If the configuration is not set up correctly, you should get a Command Not Found error or something similar when you execute the ant command. If you see this, there’s something wrong with the Ant configuration.

Open your browser of choice and point it to http://developers.android.com. On the Android developer home page, click the Develop menu item, then on the page that opens, click the Tools menu. On the page that appears, you can access the SDK directly at http://developer.android.com/sdk/index.html; you have options for downloading ADT or the new Android Studio beta.

For developers who want to use a different IDE, Google offers a separate download, the Android SDK Tools, which include the command-line tools, Android emulators, Monitor, and other tools that a developer will use for developing any Android application (regardless of which IDE is used). Regardless of which IDE you use, it’s the SDK that’s used by the Cordova CLI. In the sections that follow, I’ll quickly show you how to install ADT or Android Studio but then focus my attention on configuring the SDK tools so that the Cordova CLI can use them to manage Android projects. In Chapter 7, “Android Development with Cordova,” I show you more about how to use all of these tools for your Android application development and debugging.

Once the files have been extracted, you’ll notice that they are extracted into a folder with a long and complicated name like adt-bundle-windows-x86_64-20140702. That folder name becomes a little cumbersome when dealing with the system path later, so I always rename the folder to something simple and short like adt. Next, you want to put the files someplace where they’ll be easy to work with. I don’t like to run stuff from my system’s Downloads folder, so on Windows, I move the newly renamed adt folder to the root of the system’s main hard drive (C:adt, for example). On Macintosh OS X, I drag the adt folder to the Applications folder (/Applications/adt).

For the Android Studio installation, on Windows the SDK will be located in C:Program Files (x86)AndroidAndroid-studiosdk. On Macintosh OS X, the SDK will be located in /Applications/Android Studio.app/sdk.

If you followed my instructions in the previous sections, for ADT on Windows, the SDK will be located in C:adtsdk and on Macintosh OS X it will be located in /Applications/adt/sdk.

The SDK installation contains two folders that matter to the CLI: platform-tools and tools. To use the SDK from the CLI, we have to add these two folders to the system path on the computer running the CLI.

On Macintosh, there are several ways to update the system path. The easiest way I’ve found is to simply use a text editor to open the system’s bash profile and make some changes there. To do this, open a terminal window and invoke the default text editor using the following command:

open ~/.bash_profile

Assuming you followed the earlier instructions for adding Ant to the system path, add the full paths to the Android SDK tools and platform-tools folders to the path as shown here:

Click here to view code image

ANT_HOME=/Applications/ant
PATH=$PATH:$HOME/bin:$ANT_HOME/bin:/Applications/Android Studio.app/sdk/tools:/Applications/Android Studio.app/sdk/platform-tools
export ANT_HOME PATH

On Windows, open Windows Explorer, right-click on the Computer icon (it used to be called My Computer in older versions of Windows), and select Properties. On Windows 8, open Windows Explorer and right-click on This PC (highlighted in Figure 3.1), then select Properties. In the dialog that appears, shown in Figure 3.4, select the PATH variable at the top of the User variables list, then click the Edit button. Append the folder paths for the Android SDK platform-tools and tools folders to the existing PATH environment variable as shown in Figure 3.11, placing a semicolon between each path entry.

For this example, you’ll be appending the following text to the existing PATH entry:

Click here to view code image

c:Program Files (x86)AndroidAndroid-studiosdk ools;c:Program Files (x86)
AndroidAndroid-studiosdkplatform-tools

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.12. 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, 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 will learn more about Android development for Apache Cordova in Chapter 7.

Next, you will want to open the Macintosh App Store, search for “xcode,” and install the Xcode IDE as shown in Figure 3.13. Xcode is a huge install, so find something else to do for a while as it downloads.

The Cordova CLI requires access to the Xcode Command Line Tools in order to be able to execute builds. With older versions of Xcode, the Command Line Tools were a separate download performed within the Xcode Preferences dialog. It looks as if the tools are installed automatically with Xcode, but I wasn’t able to verify this (I had manually installed the tools before checking to see if they were already there). Open a terminal window and execute the following command:

xcodebuild

If you see a message similar to what is shown in Figure 3.14, the Xcode Command Line Tools are installed.

If not, open Xcode, open the Xcode menu, select Open Developer Tools, then select More Developer Tools. On the web page that opens, you will be able to download and install the components you need. Be sure to test that the command works after completing the installation.

You can read more about iOS development for Apache Cordova in Chapter 9, “iOS Development with Cordova.”

By default Node will install in your system path, so you can open a terminal window and type node to launch the Node application. If the prompt changes to a “greater than” symbol (>) as shown in Figure 3.15, Node is installed correctly. Press Ctrl-C twice to exit Node.

If you’re running on Linux or Macintosh OS X, you can install Git using NPM by opening a terminal window and typing

npm install –g git

On Windows, you should download Git tools and install them on your development workstation from http://git-scm.com. There are some extra Windows Explorer and shell options available through the Windows installer that cannot be installed using NPM.

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, then you should see a screen similar to the one shown in Figure 3.16.

If you receive an error message indicating that the git command couldn’t be found, the Git installation didn’t complete successfully and you will need to resolve the error before continuing.

To install the Cordova CLI on Windows, open a terminal window 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 will only be available from the current folder.

On Macintosh, you will need to install the CLI using sudo with 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. There is supposed to be a way to configure the Macintosh NPM installation so it doesn’t require sudo to install modules, but I’ve not been able to make this work on any of my systems.

NPM will spin for a while, then display the results shown in Figure 3.17.

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.18.

There’s a lot of stuff that can go wrong here, but if you’ve installed all of the prerequisites, it should just work. Where you typically run into problems is with network connectivity or proxy issues. You will have to work through any issues that impact the installation. Refer to the section “Configuring Proxy Settings” in Chapter 4, “Using the Cordova Command-Line Interfaces,” for information on how to configure proxy settings.

This happens because some of the tools needed for the CLI to launch the iOS simulator aren’t included with the Cordova download or the CLI, so you’ll have to install them manually. To fix this problem, open a terminal window and enter the following commands:

Click here to view code image

sudo npm install –g ios-deploy
sudo npm install –g ios-sim

Notice that there’s an error in the error message—the error text is instructing you to execute npm to install the required module, but on Macintosh OS X you have to execute npm using sudo as shown in the example.

npm install –g plugman

The –g in the command tells NPM to install Plugman globally; if you did not use this parameter, Plugman will only be available from the current folder.

On Macintosh, you must install Plugman using sudo with the following command:

sudo npm install –g plugman

To confirm that the installation completed successfully, execute the following command:

plugman

If Plugman is installed correctly, you should see a help page returned to the console similar to what is shown in Figure 3.20.