devxlogo

Setting Up PhoneGap on Windows and OSX Using the Command-Line

Setting Up PhoneGap on Windows and OSX Using the Command-Line

PhoneGap has quickly become a popular platform for building mobile applications, mainly because of the simplicity involved in creating cross-platform applications using only HTML, CSS and JavaScript. The idea is simple – you build your application in HTML5, and then add that code to your PhoneGap application, and it compiles to Android, IOS and Windows for you. PhoneGap even gives you plugins that allow you to access your device Camera, Compass, Contacts, GPS and much more. This means that you can access functionality formerly only available to the native device language using JavaScript.

In this article we are going to look at how to install PhoneGap, using the command-line interface, on Windows and MAC OS X. One caveat here is if you want to build IOS applications, you have to have your PhoneGap installation on a Mac running OS X and Xcode. For Windows Mobile, you must build your PhoneGap application in a Windows environment. Android (built in Java, essentially) can be built anywhere. Most developers I know either have a Mac with Windows installed as a Bootcamp or a Mac running Windows in a virtual machine like VMware or VirtualBox. Creating all three platforms is then as simple as copying the HTML from OS X to Windows, or vice versa.

We will be dealing with the latest stable build of PhoneGap at the moment, which is 3.1.0. I used Windows 8.0 and OS X Mavericks for this tutorial.

Install Node on Windows

To setup PhoneGap on Windows, we need to install node.js on our machine. If you do not have Node yet, head over to http://nodejs.org/ and hit the install button. This will download the Node installer. Run the installer and follow this process:


Click ‘Next’ to get started


Accept the license terms and click ‘Next’


Change the install location if you want to, and click ‘Next’


Select which features you would like installed. Default is ‘all’, which is good.


Click ‘install’ to start running the installer


Wait for the installer to complete


Success!

Install Node on OS X

To setup PhoneGap on OS X, we again need to install node.js on our machine. If you do not have Node yet, head over to http://nodejs.org/ and hit the install button. This will download the Node installer.

Double click on package you have downloaded, and follow this process:


Click ‘Continue’ to get started


Read the license terms (if you must) and click ‘Continue’


To agree to the license terms, click ‘Agree’


Choose which hard drive to install node on. Usually the default is your current drive Click ‘Install’.


Once the installer is done, click close.

To check if node is installed, you need to open your terminal. Click on the spotlight icon on the top right of your status bar (it’s a magnifying glass) and type ‘terminal’ in the search box that appears. Select ‘Terminal’ listed next to ‘Applications’.

When the terminal has opened, type: ‘node -v’. You should get a version number without any errors popping up (mine shows version v0.10.22). If you have errors, head on back to the Node website and check out the support documentation. If you have no errors showing up at this point, you’re done!

Install PhoneGap

Next, we need to install the PhoneGap command-line utility. We do this using Node, on the Windows Command Line or Mac Terminal that we previously opened.

In Windows 7, click on start, and type “cmd” in the search box. This will open your terminal window.

  • In Windows 8, click the “windows” button on your keyboard and type “cmd”.
  • In OS X use spotlight (as detailed above) if your terminal is not still open.

The Commands for Windows and OS X PhoneGap Installation are Identical

Inside the command line terminal, type:

$ npm install -g PhoneGap

‘npm’ Is the Node Package Manager, and is the reason we needed to install Node.

If you get permission errors on OS X, you may need to run the command as the root user, as follows:

$ sudo npm install -g PhoneGap

This will ask you to confirm your password before installing PhoneGap.

Create the PhoneGap App

Now that PhoneGap is installed on your system, you can create the PhoneGap app.

Using the command-line utility, navigate to the directory that you want your application to reside in (if you want to test your application in a standard browser, this will need to be on a webserver like XAMP). Once in the directory of your choice, you need to run the command to tell PhoneGap to create the application. The syntax looks like this:

$ PhoneGap create myProject com.example.myProject MyProject

PhoneGap create– tells PhoneGap to create a new project and expect more arguments.

  • myProject– is the name of the directory that the application will be created in.
  • com.example.myProject– the reverse-domain style identifier for your project. If you are unsure what to use, use this example.
  • MyProject – the display name of your application when it is deployed to the device.

File Structure

Once the project is created, you will notice the following directories in your project root:

  • merges – Contains shared code between the platforms. This is maintained by PhoneGap and you should never touch it.
  • platforms – PhoneGap builds your IOS, Android, Windows and other platforms native code here. Don’t touch.
  • plugins – PhoneGap installs your plugins here. These are PhoneGap specific plugins and should not be touched.
  • www – This is where you do your work. Contains js, css, img and a few other directories specific to PhoneGap. The usage here is out of the scope of this tutorial, but in general, everything starts with the index.html file in this directory.

Build the App

Next, we need to enter the application directory.

$ cd myProject

If we are running OS X and have Xcode installed, we can build an iOS application at this point. Simply run the following in your terminal:

$ PhoneGap build ios

And the response you will see in your terminal is:

[PhoneGap] detecting iOS SDK environment...[PhoneGap] using the local environment [PhoneGap] compiling iOS...[PhoneGap] successfully compiled iOS app

When this is done, you will notice an ‘ios’ directory in the platforms directory of your application. This directory contains your iOS-specific code that Xcode requires to build your application.’

Similarly, to build an Android application alongside the IOS application, run:

$ PhoneGap build android

This will build an ‘android’ directory in the ‘platforms’ directory.
Android applications can be built on Windows as well as OS X.

On your Windows machine, you can build a Windows Mobile application by running:

$ PhoneGap build Windows

It is important to note that you will only ever work in your ‘www’ directory. When PhoneGap compiles your application, it takes all of your code you have created or edited, and adds it to your IOS, Android, or Windows platforms, so you write once, run everywhere (at least for mobile).

Installing Features

The whole point of using PhoneGap, rather than just a mobile web view, is that PhoneGap gives you access to the mobile device hardware like the camera, GPS, etc. In order to use these features, we need to install PhoneGap plugins. These are done on the command line, and again, OS X and Windows commands are identical.

Device API

This allows you to obtain device information, like platform, IMEI, and more.

$ cordova plugin add org.apache.cordova.device

Network Connection and Battery

$ cordova plugin add org.apache.cordova.network-information$ cordova plugin add org.apache.cordova.battery-status

Accelerometer, Compass, and Geolocation

$ cordova plugin add org.apache.cordova.device-motion$ cordova plugin add org.apache.cordova.device-orientation$ cordova plugin add org.apache.cordova.geolocation

Camera, Media Playback and Capture

$ cordova plugin add org.apache.cordova.camera$ cordova plugin add org.apache.cordova.media-capture$ cordova plugin add org.apache.cordova.media

Access Files on Device or Network (File API)

$ cordova plugin add org.apache.cordova.file$ cordova plugin add org.apache.cordova.file-transfer

Notification via Dialog box or Vibration

$ cordova plugin add org.apache.cordova.dialogs$ cordova plugin add org.apache.cordova.vibration

Contacts

$ cordova plugin add org.apache.cordova.contacts

Globalization

$ cordova plugin add org.apache.cordova.globalization

Splashscreen

$ cordova plugin add org.apache.cordova.splashscreen

Open New Browser Windows (InAppBrowser)

$ cordova plugin add org.apache.cordova.inappbrowser

Debug Console

$ cordova plugin add org.apache.cordova.console

Deploy to Device

To deploy to your device, you need to do the following:

Android

Make sure your device is in developer mode, and has USB debugging turned on. Connect your device to your machine and, in the command-line, type:

$ PhoneGap run android

If your Android SDK is correctly installed on your machine, you will see, after a few minutes, that your application will open on your device.

If you want to test your application on an emulator, do the same as above, but with no device connected to your computer.

iOS

This is a little more complicated. Firstly, you need an Apple Developer account if you want to deploy to your device for testing (you can test the device on the Xcode emulator without a certificate, but Apple will not accept your application into the App Store without it being tested on at least one real device). Once this is done and you have setup a provisioning certificate for your device (see http://developer.apple.com/), you need to compile your IOS application. In your Terminal, type:

$ PhoneGap build ios

Your response in the Terminal should be:

[PhoneGap] detecting iOS SDK environment...[PhoneGap] using the local environment[PhoneGap] compiling iOS...[PhoneGap] successfully compiled iOS app

Now that your IOS application is compiled, you need to launch Xcode. Use Spotlight as before, and once Xcode is open, select ‘File’, then ‘Open…’ and from the file browser, navigate to your PhoneGap project. Open the ‘platforms/ios’ directory, and search for the file called ‘{yourprojectname}.xcodeproj’ and double click on it. This will open your project in Xcode.

Look at the top left of your Xcode window. You should see a ‘Play’ button (arrow pointing right), and a ‘Stop’ button (a square), and next to that, the name of your application. Next to that will be the name of an emulator – mine says iPhone Retina (4-Inch 64 Bit). If you have your iPhone, iPod or iPad plugged in, you can click on that and select your device. Then press the play button. This will build your project again in Xcode, and try to deploy it to your device. If your device is not plugged in, it will deploy it to the emulator you have selected, as seen below:

Note that every time you edit your PhoneGap project, you need to run the ‘PhoneGap build’ command before trying to run the application in Xcode. The reason is that the ‘PhoneGap build’ command copies your code from your ‘www’ directory to the ‘platform/ios/’ directory, and only then can Xcode see that your project has changed, and apply the changes.

Conclusion

Now that you have your PhoneGap application running, it’s time to start with the fun stuff – building something. Remember, you are only limited by your imagination and your knowledge of HTML, CSS and JavaScript. For more information on how to use PhoneGap, you can read the official documentation here.

devxblackblue

About Our Editorial Process

At DevX, we’re dedicated to tech entrepreneurship. Our team closely follows industry shifts, new products, AI breakthroughs, technology trends, and funding announcements. Articles undergo thorough editing to ensure accuracy and clarity, reflecting DevX’s style and supporting entrepreneurs in the tech sphere.

See our full editorial policy.

About Our Journalist