13. Using the PhoneGap CLI
The PhoneGap CLI is a command-line tool developers use to create and manage PhoneGap application projects. You can use the CLI to interact with local development projects, just as you do with the Cordova CLI (described in Chapter 4, “Using the Cordova Command-Line Interfaces”), but you can also use it to work with the PhoneGap Build service from the command line. In this chapter, I show you how to use the PhoneGap CLI for your projects, focusing most of my attention on how the PhoneGap CLI differs from the Cordova CLI.
The PhoneGap CLI operates the same way as the Cordova CLI demonstrated in Chapter 4. You open a terminal window, navigate to where you want a project created or to an existing PhoneGap project folder, and execute one or more commands by typing the text of the command and pressing the keyboard’s Enter key. With the latest release, the PhoneGap CLI has access to the entire Cordova CLI command structure plus some extra commands.
Getting Help
The easiest way to learn about the capabilities of the PhoneGap CLI is to use the built-in documentation included with the CLI. To have the PhoneGap CLI display its help options in the terminal window, execute one of the following commands:
phonegap
phonegap –h
phonegap help
phonegap --help
For help with a particular command, you can use any one of the following:
phonegap <command> -h
phonegap <command> help
phonegap <command> --help
phonegap help <command>
As an example, to learn more about the phonegap create command options, you would execute one of the following:
phonegap create -h
phonegap create help
phonegap create --help
phonegap help create
For the create command, this does cause a slight problem. Remember from Chapter 4 that there are multiple forms of the create command: one where you simply provide the target project folder and the CLI uses some default settings and another where you provide all of the options on the command line. So, to create a project in a folder called help, you should be able to issue the following command:
phonegap create help
Unfortunately, this doesn’t work. What you’ll see when you issue this command is the command-specific help content for the create command. To create a project in a target folder called help, you must use the full version of the command:
phonegap target_folder appID appName
So, for my project called “help,” the command would look like the following:
phonegap help com.ac4p.help Help
Project Management
As described in the sidebar, you can use the same Cordova CLI commands with the PhoneGap CLI, simply replacing cordova with phonegap in each command. With that in mind, the typical new project workflow will look something like the following:
phonegap create target_folder
cd target_folder
phonegap platform add platform_list
phonegap plugin add plugin
phonegap prepare
phonegap run platform
So, to create the Lunch Menu app we’ve discussed in previous chapters, use the following:
phonegap create lunchmenu
cd lunchmenu
phonegap platform add android ios windows
phonegap plugin add org.apache.cordova.console
phonegap plugin add org.apache.cordova.dialogs
phonegap plugin add org.apache.cordova.device
phonegap prepare
phonegap run android
That’s it. With the latest version of the PhoneGap CLI, it should look and feel just like the Cordova CLI we’ve used throughout the book. All the other commands you learned in Chapter 4 should work here.
Anatomy of the Default PhoneGap Application
When you run this quick sample application, the application will render the page shown in Figure 13.1; this is almost the same sample app we’ve seen before in Figure 2.6, only showing the PhoneGap logo instead of the Cordova logo and slight changes in the page text.
I haven’t added any of my own code to this project; I simply used the default project that PhoneGap uses. If you compare the application to the default Cordova application, there are some very small differences.
For the project’s config.xml file (described in Chapter 5, “The Mechanics of Cordova Development”), Figure 13.2 shows a line-by-line comparison of the default file for this PhoneGap project and the default Cordova project. As you can see from the figure, mostly minor, descriptive differences appear between the files. The only major difference is the addition of the preferences element for the PhoneGap project. Preferences elements are used by the PhoneGap Build service and described briefly in Chapter 12, “Using PhoneGap Build.”
The only other differences between the two applications are that the PhoneGap version of the application has the call to initialize the application in a script tag in the index.html file:
<script type="text/javascript">
app.initialize();
</script>
The same call in the Cordova version of the application is simply appended to the end of the index.js file.
If there happens to be a Cordova CLI command that isn’t directly supported by the PhoneGap CLI, you can use the PhoneGap CLI to pass the command on to the Cordova CLI like so:
phonegap cordova command command_parameters
So, to use the cordova create command from the PhoneGap CLI, you would simply execute the phonegap command and pass in the cordova command structure:
phonegap cordova create lunchmenu com.ac4p.lunchmenu "Lunch Menu"
However, this result can be obtained by simply using the following command:
cordova create lunchmenu com.ac4p.lunchmenu "Lunch Menu"
So I’m not quite sure what the value is of typing those extra eight characters as both commands deliver the same result as far as I can tell.
PhoneGap CLI Workflow Differences
As I’ve shown, the PhoneGap CLI workflow is pretty much the same as the Cordova CLI workflow. There are, however, some places where the PhoneGap workflow differs. When you create a new PhoneGap project, you don’t need to add the platforms to the project; you can add them at build time instead. For example, using the Lunch Menu example from earlier, you could create the project and add the plugins as shown:
phonegap create lunchmenu
cd lunchmenu
phonegap plugin add org.apache.cordova.console
phonegap plugin add org.apache.cordova.dialogs
phonegap plugin add org.apache.cordova.device
Then, after you have added your web application content and you’re all ready to test, you can add the Android platform to the project using the following command:
phonegap run android
Here the PhoneGap CLI will first add the platform (or platforms if you provided several on the command line), then execute prepare before starting the build process. This isn’t a huge benefit as you’re still adding each platform as needed; I believe this was added to support interacting with the PhoneGap Build service described in the following section.
Note
On the Cordova dev list recently, a developer requested that this same feature be added to the Cordova CLI. Michael Brooks from the PhoneGap team said he would add it, so you may be able to use this same feature with the Cordova CLI by the time you read this.
Interacting with the PhoneGap Build Service
So far, everything we’ve done has targeted a local PhoneGap project. That’s fine, since you have to first create a local project and populate it with the necessary plugins and web application content before you can upload it to the PhoneGap Build service.
With earlier versions of the PhoneGap CLI, you instructed the CLI to work with a local project by prefacing every command with local. With the current version, the local parameter is being deprecated, and going forward the PhoneGap CLI will assume you’re working with a local project until you tell it otherwise.
From a workflow standpoint, you can either create your project locally, then build and test using the local SDKs, or you can create the project locally and use the PhoneGap Build service to complete the build process for you. For the PhoneGap Build workflow, when you have your local project all ready to go, you use the phonegap remote command to switch the CLI context from the local project to the PhoneGap Build service.
Before you can work with the PhoneGap Build service from the command line, you must first log in to the service. The system will prompt you to log on the first time you try to use the remote command, or you can initiate the login process by opening a terminal window and issuing the following command:
phonegap remote login
In the following example, you can see the entire command-line process for creating the sample Lunch Menu application:
C:Usersjwargodev>phonegap create lunchmenu com.ac4p.lunchmenu "Lunch Menu"
Creating a new cordova project with name "Lunch Menu" and id
"com.ac4p.lunchmenu" at location "C:Usersjwargodevlunchmenu"
Using custom www assets from https://github.com/phonegap/phonegap-app-hello-worl
d/archive/master.tar.gz
C:Usersjwargodev>cd lunchmenu
C:Usersjwargodevlunchmenu>phonegap plugin add org.apache.cordova.console
Fetching plugin "org.apache.cordova.console" via plugin registry
C:Usersjwargodevlunchmenu>phonegap plugin add org.apache.cordova.dialogs
Fetching plugin "org.apache.cordova.dialogs" via plugin registry
C:Usersjwargodevlunchmenu>phonegap plugin add org.apache.cordova.device
Fetching plugin "org.apache.cordova.device" via plugin registry
At this point, the project has been created and all I have to do is populate the project with the appropriate web application content. Once the project is all ready, I can use the PhoneGap CLI build and run commands to build the app and test it using a simulator or physical device.
However, in this example I want to use the PhoneGap Build service to manage the build process, so I can initiate a remote build of the application using the following command:
phonegap remote build platform_list
To build for a single platform, I would provide the platform name at the end of the command:
phonegap remote build android
To build for multiple platforms, simply append the platform list to the end of the command:
phonegap remote build android ios windows
The CLI will return the following results:
C:Usersjwargodevlunchmenu>phonegap remote build android
[phonegap] compressing the app...
[phonegap] uploading the app...
[phonegap] building the app...
[phonegap] Android build complete
What happened is that the CLI packaged the web application in a .zip archive, created a new (or updated an existing) project on the Build service, and kicked off the Android build process. If I’d provided additional platforms with the command, the Build service would have started the build process for each platform.
On OS X, this worked without a hitch. On Windows, however, it may fail and display the error dialog shown in Figure 13.3.
I had configured my development system so that JavaScript files open automatically in my editor of choice, and apparently the PhoneGap CLI has an issue with that. To get around this problem, I had to start the Windows terminal application with administrator privileges and issue the following command:
assoc .js=JSFILE
This resets some internal file associations and allows the PhoneGap CLI to complete its work.
At the conclusion of the process, you can log in to the PhoneGap Build service and see the application listed as shown in Figure 13.4.
From here on in, the Build service operates as described in Chapter 12. The PhoneGap CLI provides an easier way to upload updates and initiate the build process from the CLI.
Wrap-Up
In this chapter, I showed you how to use the PhoneGap CLI to manage PhoneGap application projects. I highlighted some of the differences from the Cordova CLI, then showed how to use the CLI to upload projects to the PhoneGap Build service. With these tools in hand, you now have additional tools to use with your hybrid application projects and an easier way to upload updates to your application to the Build service.