Setting Up Your Development Environment for Cordova Android projects

Updated 8/2/2015 to include Windows 7 setup. Adobe PhoneGap/Apache Cordova CLI quickly sets up your project files for the mobile environment. However, it requires a hefty setup of your development environment before you can begin making Android apps. If you are a working developer, all these tools are par for the course and you’ll have them already installed. If you are trying out Cordova/PhoneGap for the first time, and you are new to the programming world – welcome! – you need to install all the “dependencies” that Cordova/PhoneGap assumes are already resident on your system. Follow all these steps to make your Cordova/PhoneGap work go smoothly. Of course, these steps need to be done just once.

Install ADT + Eclipse

I no longer install Eclipse. Install Android Studio instead.

a. After the AS installer starts, it will ask you to link to the JDK location. If you can’t do that, then click on the link the installer gives. (In my case, I clicked through and selected Java SE Development Kit for Windows X64. It installed the jdk1.7.0_79 files in C:\Program Files\Java\.

b. Navigating to this folder in the AS installer, I was met with rejection of the folder, even though it met the requirements of housing /bin/java.exe and being 1.7 or higher. I simply deleted the URL in the box and clicked on Next to continue and install AS. At this point, about 60 min. have elapsed.)

c. Then jump down to Install Node and npm below.

1. Users often use Eclipse with Cordova/PhoneGap projects. To download, hit the “Download Eclipse ADT with the Android SDK for xxx” button from http://developer.android.com/sdk/index.html (ADT = Android Development Tools.)
2. I uncompressed and moved the /adt-bundle-mac-x86_64 folder to /Developers. This page gave a little more information on setting up the files, which we will follow next: http://developer.android.com/sdk/installing/installing-adt.html
3. Start Eclipse, then select Help > Install New Software. (To start Eclipse, click on the Spotlight icon in the upper right of your desktop and type in eclipse to find it.)
4. In Eclipse, click on Add in the top-right corner.
5, In the Add Repository dialog that appears, enter “ADT Plugin” for the Name and enter the following URL for the Location: https://dl-ssl.google.com/android/eclipse/
6. Click OK. If you have trouble acquiring the plugin, try using “http” in the Location URL, instead of “https” (https is preferred for security reasons).
7. In the Available Software dialog, select the checkbox next to Developer Tools and click Next.
8. In the next window, you’ll see a list of the tools to be downloaded. Click Next.
9. Read and accept the license agreements, then click Finish. If, during the install process, you get a security warning saying that the authenticity or validity of the software can’t be established, click OK.
10. When the installation completes, restart Eclipse.

Install the Android SDK 

Android provides its own SDK to help us build applications that run in the Android environment. (SDK = Software Development Kit.)

1. When I restarted Eclipse in the last section, a dialog box popped up telling me that the “Location of the Android SDK has not been setup in the preferences.” I clicked on the Open Preferences button in that dialog.
2. In the Preferences dialog, Hit the Browse button to navigate to the /adt-bundle-mac-x86_64/sdk folder and clicked Open.
3. Click on Apply. An SDK Target will appear in the panel for the Android Preferences. In my case, Android 4.4W, API level 20. (The W means it’s for Android Wear projects. API = Application Programming Interface.)
4. Click on Apply again, then OK.
5. There was a Welcome to Android Development window waiting for me, requesting the SDK location. I chose to “Install new SDK” and checked both boxes under that heading. Click Finish.
6. Select Accept All and Install to begin the long download. Whew! Almost done.
7. You might get an alert in Eclipse informing you that an update was available. Click on the notice and answer positive to the next few prompts.
8. After the install, a dialog tells me to open the SDK Manager, so I chose that button. The Android SDK Manager window opens.

Android SDK Manager 

Android SDK allows us to choose which level of API we want to develop for and preview in a emulator. So in its on-screen emulator, it will show you what parts of your app work well and which parts don’t. So choose several different APIs. Each time Android comes out with an update, it receives a new API number. The latest at this writing is 23. Do not choose an API below 11. You’ll want to choose an API level that you know you’ll be coding for specifically, if you know it. (I believe that choosing the latest API makes it backwards-compatible.)

To get the Android SDK Manager running, open Terminal or Command Prompt and type:

android

1. I selected all files for API 19, the number for my device. (To find this number, I open Settings in my Nexus 7 and choose About tablet. Android version is noted as 4.4.2. That corresponds to API 19 in the SDK Manager. You want to choose an API no lower than that number – later APIs are backwards-compatible.) To choose the lowest number, read this: http://developer.android.com/about/dashboards/index.html I clicked on Android 4.4.2 (API 19). (API = Application Programming Interface.) Go ahead and select any other packages you know you’ll need. Also review the package “Extras” to see if you need any of those.
2. I clicked on the button saying, “Install xx packages..”
3. I clicked on each of the package names at left and its Accept License button, then on Install. The installation may take 15-60 minutes, depending on which packages you chose and the speed of your computer. Don’t be fooled by the progress in percentages – that is per file, not for the complete download!
4. Exit the SDK Manager (click on the red light at upper left) and click on Help > Check for Updates to look for updates to the the software you just downloaded. This process will take several minutes.

Anytime you want to open Android SDK Manager later, go to Window > Android SDK Manager.

Install Node and npm

1. Cordova uses Nodejs and npm to install its software on your system. I downloaded both from http://nodejs.org/. It downloaded in my Mac as node-v0.10.13.pkg in /Downloads. I double-clicked its icon to start the installation. (npm = Node Package Manager.)

2. An installer appeared saying, “This package will install node and npm into /usr/local/bin.” I hit Continue and followed the prompts. The final Mac screen said,

Node was installed at 
/usr/local/bin/node
npm was installed at 
/usr/local/bin/npm

(usr = User. bin = binary.)

In Windows, Node and npm were installed at C:\Program Files\nodejs.

Install Ant

Apache Ant is needed. Download it from http://ant.apache.org/bindownload.cgi. I downloaded the zip version, right-clicked and selected Uncompress in Mac. I dragged the /apache-ant-1.9.3 folder to the /Developer folder. (Ant = Another Neat Tool.) In Windows I downloaded the zip version to Downloads, then dragged the apache-ant-1.9.6 folder to C:\Program Files.

Install JRE

Oracle JRE is needed. Download it from: http://www.oracle.com/technetwork/java/javase/downloads/jre7-downloads-1880261.html. I chose the .tar.gz download for Mac OS X x64 (Do you have a 32-bit processor or 64-bit? Find out here: http://32or64.com). In Mac, right-click and Uncompress. I moved the /jre1.7.0_51.jre folder to /Developer. (JRE = Java Runtime Environment.) In Windows, move the file to C:\Program Files\.

Set up the PATH statements in Mac

We need to let the system know where our program files are so that the Mac Terminal or Windows Command Prompt will be able to find and run them. To do that, we’ll modify our Mac’s hidden .bash_profile file with a text editor and Window’s Environment Variables dialog box. The console will look up this file and apply the shortcuts to the commands. (If you can’t see your Mac’s hidden files, read further down for instructions on showing them.)

1. Get the path to your Mac’s adt-bundle-mac-x86_64 folder, in my case: ~/Developer/adt-bundle-mac-x86_64/. (The ~ is a shortcut for /Users/<name>.)

2. If you can see your hidden files, go to /Users/<name>/.bash_profile and open it in a text editor. Check to see if the following lines are there, but check each line and modify to match your own system’s setup.

#tools
export PATH=${PATH}:~/Developer/adt-bundle-mac-x86_64/sdk/platforms
export PATH=${PATH}:~/Developer/adt-bundle-mac-x86_64/sdk/platform-tools
export PATH=${PATH}:~/Developer/adt-bundle-mac-x86_64/sdk/tools

#ant
export ANT_HOME=~/Developer/apache-ant-1.9.3/bin
export PATH=${PATH}:${ANT_HOME}/bin

#bin path
export PATH=${PATH}:~/bin
export PATH=${PATH}:~/usr/local/bin

#JRE
export PATH=${PATH}:~/Developer/jre1.7.0_51.jre/Contents/Home/bin

#Java JDK -- no higher than jdk 7, please
export JAVA_HOME=/System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home
export PATH=${PATH}:${JAVA_HOME}/bin

Update! When I installed Android Studio in the Mac, the Android SDK Manager displayed an address in the SDK Path field at top with this address: /Users/Steve/Library/Android/sdk. So Android Studio’s files will be put tehre by default. So the above #tools PATH statements will need to be changed to (“~” = /Users/Steve) :

#tools: android, draw9patch, zipalign, etc.  
# "~" = /Users/Steve

export PATH=${PATH}:~/Library/Android/sdk
export PATH=${PATH}:~/Library/Android/sdk/platforms 
export PATH=${PATH}:~/Library/Android/sdkplatform-tools 
export PATH=${PATH}:~/Library/Android/sdk/tools

Test the PATH Statements

Let’s test that the .bash_profile entries are correct. In the Terminal first type . .bash_profile (that’s a space between the two periods) to reset the file so Terminal knows it’s been updated.

a. Type java -version then tap Enter. You should get information about about Java. I got:

java version "1.6.0_65"

b. Type ant -version then tap Enter. You should get information about about Ant. If not (“command not found”), check your .bash_profile for a typo in the path. I got:

Apache Ant(TM) version 1.9.3 compiled on December 23 2013

c. Type android -h then tap Enter. The help for android commands should appear. If you get:

can't find sdkmanager.jar

… then complete quit Terminal and open it again, and type it again.

Show Hidden Files in Mac

To show the system’s hidden files which begin with a period, such as .bash_profile, type in Terminal:

defaults write com.apple.finder AppleShowAllFiles TRUE

. . . and hit Return. When the prompt returns type in Terminal:

killall Finder

. . . and hit Return. The desktop will go blank, then after a while will refresh. Open the Documents folder, then in Finder, Go > Enclosing Folder, and see the hidden files in gray with a dot before their filename.

To hide the hidden files, repeat both commands, but substitute FALSE in place of TRUE for the first command.

Set up the PATH statements in Windows

In Windows, you put all this PATH information in another place.

1. Click Start then Computer. Right-click on Computer in the left folder menu and select Properties then on Advanced system settings. Click on Environment Variables… Note that there are two main text areas. We are only going to fill in the lower section.

2. Scroll down until you come to Path. Double-click to open it. I have the following added to the end:

C:\Program Files\Java\jre7\bin;

C:\Program Files\nodejs;

C:\Program Files\apache-ant-1.9.6\bin;

C:\Program Files\Java\jdk1.7.0_79\bin;

C:\Users\Our Computer\AppData\Local\Android\sdk;

C:\Users\Our Computer\AppData\Local\Android\sdk\build-tools;

C:\Users\Our Computer\AppData\Local\Android\sdk\platform-tools;

C:\Users\Our Computer\AppData\Local\Android\sdk\tools;

It’s a good idea to find and open these folders to make sure they are all on your system. (This is Windows 7.) I couldn’t find the \AppData folder right away. To find it, I first had to click on Tools > Folder Options in the file manager window, click on the View tab, and under Hidden files and folders, check the box for Show hidden files, folders, and drives, then OK.

In the environment variables box, the listing above is all on one line like this:

C:\Program Files\Java\jre7\bin;C:\Program Files\nodejs;C:\Program Files\apache-ant-1.9.6\bin;C:\Program Files\Java\jdk1.7.0_79\bin;C:\Users\Our Computer\AppData\Local\Android\sdk;C:\Users\Our Computer\AppData\Local\Android\sdk\build-tools;C:\Users\Our Computer\AppData\Local\Android\sdk\platform-tools;C:\Users\Our Computer\AppData\Local\Android\sdk\tools

3. Click OK to close the environment variables dialog. Shut down the other windows that led you there.

4. To get the console to recognize the changes, shut down the command prompt and open it again, then follow the next steps. If they don’t work, save your work, log out of Windows, log back in, then try the steps again.

Test the PATH Statements

Let’s test that the environment variables entries are correct. Open the Command Prompt if it isn’t already.

1. Type java -version then tap Enter. You should get information about about Java. I got:

java version "1.8.0_25" 
Java(TM) SE Runtime Environment (build 1.8.0_25-b18)

2. Type ant -v then tap Enter. You should get some scary-looking information, but look for this line:

Apache Ant(TM) version 1.9.6 compiled on June 29 2015

(If you get Buildfile: build.xml does not exist! then try ant -version instead.)

3. Type npm then Enter. You should get an overview of available npm commands.

4. Type android then Enter. The SDK Manager window should come up. Let’s take care of that now:

5. Click on the check boxes for your device’s API. (To find this number, I open Settings in my Nexus 7 and choose About tablet. Android version is noted as 4.4.2. That corresponds to API 19 in the SDK Manager.) To choose the lowest number, read this: http://developer.android.com/about/dashboards/index.html I clicked on Android 4.4.2 (API 19). (API = Application Programming Interface.) Click on as many APIs as on the devices with which you will test the app. You want to select the API with its Platform-tools and Build-tools selections.

6. When all the selections have been made, click on the Install xx packages button, click on each package and accept the license, then Install. Exit when done.

Install Cordova (Mac and Windows)

Download Apache Cordova from http://cordova.apache.org/.

In the Mac Terminal, type the following and hit Enter:

sudo npm install -g cordova

or

sudo npm install -g phonegap

(sudo info: http://www.courtesan.com/sudo/intro.html. -g = global, which means you’ll be able to use the command no matter which folder the command started from.)

Test the install. Type cordova -v. I got:

4.0.0

In Windows, open the Command Prompt window (Start button > All Programs > Accessories)  and type the following, and hit Enter:

npm install -g cordova

Test the install: type cordova -v. I got:

5.1.1

(These Windows instructions were added at a much later date, so I show a later version.)

Download a Cordova/PhoneGap debugging system (optional)

You’ll need to test your app during formation. Choose from one of these debugging tools:

A. PhoneGap Developer App

Cordova released the Developer App, in which you download their app onto your device, run a cordova server in the terminal, and view your app on the device without having to download and install it to the device. You can make changes to your app and instantly see them in the device. For more information on this, see my steps (although this is for an early version – it is being aggressively updated): https://iphonedevlog.wordpress.com/2014/05/02/app-testing-with-the-phonegap-app-see-your-changes-instantly-without-re-building/

B. Genuitec’s GapDebug

You can debug your device with GapDebug if it has Android 4.4 or later.

In your device, check Settings > About to see if you have 4.4 or later. (My device had 4.3, so I could not complete these steps.) If so, do the following.

1. Download GapDebug from https://www.genuitec.com/products/gapdebug/ to debug your app. It downloads a .dmg file. (dmg = disc image.)  I clicked on the button in the browser after it downloaded and a window opened with the installer app icon showing. Double-clicked on that to install.
2. In your /myApp/platforms/android/AndroidManifest.xml file, include:

<application android:debuggable="true"

3. In your device, open Settings > Developer Options and enable USB Debugging. (If Developer Options is not listed, open the About details, tap the Build Number field 7 times, and then select Back to view Developer Options.)

Check the Learning Center for all the steps: https://www.genuitec.com/products/gapdebug/learning-center/

C. Apache Ripple

Ripple displays its business in the Chrome browser, so you need Chrome downloaded to use it.

Install Ripple with npm installed via the Terminal with:

npm install -g ripple-emulator

Then run the following from the root folder of your app:
ripple emulate

For more: http://www.raymondcamden.com/2013/11/5/Ripple-is-Reborn

D. Weinre

Instructions on use this debugger is here: https://iphonedevlog.wordpress.com/2012/07/24/installing-weinre-remote-debugger-on-the-mac-osx-lion/

Setup Complete

At long last your system is now set up to start building your first basic Apache Cordova or Adobe PhoneGap project! Some projects are more involved and will require more software dependencies to run. Check your software requirements carefully — it’s your responsibility to read the docs on the phonegap.com site.

Go to https://iphonedevlog.wordpress.com/workflow/ and check out New App to start creating a Cordova app. It assumes you already have your basic HTML/CSS/JS code ready to go. If you don’t know about this, then you need to learn more, so read: https://iphonedevlog.wordpress.com/explanation-of-phonegapcordova-for-the-layman/