4. Using the Cordova Command-Line Interface
As mentioned in Chapter 2, included with the framework files for most of the supported mobile device platforms are scripts that you can use to create new projects and test/debug applications. The problem with these scripts is that they’re specific to each mobile device platform and therefore can’t be used to manage a cross-platform project in its entirety.
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 use the Cordova CLI to manage Apache Cordova application projects.
About the CLI
Because Cordova applications are web applications and can be coded using any text editor, and the mobile device manufacturers use different integrated development environments (IDE) and project structures for building native applications, there wasn’t a single, simple way to create and manage Cordova applications for multiple mobile device platforms. With earlier versions of Cordova, developers had to create multiple projects, one for each mobile device platform, and copy the web application code between the projects. In Cordova 3.0, the project also migrated all of the Cordova APIs to plugins, so managing your Cordova projects, web content, and installed plugins could be quite difficult.
Beginning with Cordova 3.0 (actually, the CLI was available in prerelease form in Cordova 2.7), the project added a CLI that provides a suite of commands a developer can use to
Create cross-platform Cordova application projects
Add support for each of the Cordova supported mobile device platform
List supported mobile device platforms
Remove support for a mobile device platform
Add a plugin to a project; this can be a core Cordova plugin, a third-party plugin, or a plugin you’ve created yourself
List plugins installed in a project
Remove a plugin from a project
Prepare, compile, and build projects
Serve an application project’s web content via a web server
Launch an application in the appropriate mobile device simulator
With these commands in place, a developer can manage the complete lifecycle of a Cordova application. Each of these options is described throughout the remainder of the chapter.
Troubleshooting the CLI
It’s never good to start a chapter with troubleshooting information, but when working with the CLI, there will be times when you wish you could tell more about what’s happening behind the scenes when a command is running. Right after Cordova 2.8 was released, the project team added a verbose mode to the CLI. To enable verbose mode, add a -d or --verbose to any CLI command.
For example, the following Cordova command returns nothing; it does its work and quits:
cordova build android
In general, as long as the command works before returning nothing to the terminal window, that’s okay, but when working with a command that fails silently or fails with an unclear error message, it’s useful to be able to see exactly what’s happening with the command.
If you issue the following command instead:
cordova -d build android
the terminal window will fill with more than 100 lines of text (which I won’t list here) that shows the status of every step performed by the CLI during processing of the command. Some of the information is provided by the CLI commands, but some is generated by any third-party tool called by the CLI.
Note
It’s interesting to see how many different programs are called by the CLI as it does its work. The default terminal on Macintosh will change the contents of the terminal window title bar with every external program called by a script. For some longer running processes, it’s fun to watch the title bar to see how much stuff is really going on.
CLI Command Summary
Table 4.1 provides a summary of the available CLI commands; the sections that follow describe the operations in greater detail.
Using the CLI
In this section, I show you how to use the commands exposed through the Cordova CLI. I cover the mechanics of the commands and what happens when each is executed. Look to Chapter 6, “The Mechanics of Cordova Development,” for more information about the Cordova application project files.
To learn more about what commands are available in the CLI, you can open a terminal window (or Windows command prompt—I’m just going to call it a terminal window going forward) and get help by typing:
cordova help
You can also check the CLI version number by using the following command:
cordova –v
or
cordova –version
Creating a Cordova Project
Before you can do any Cordova development, you must first create an application project. To help you, the Cordova CLI includes a create command, which is used to create new projects.
To create a new Cordova project, open a terminal window and navigate to the folder where you want the project folder created, then issue the following command:
cordova create project_folder
This creates a simple Cordova project structure and web content files you need for the application. You can also specify an application ID and application name using the following command:
cordova create project_folder app_id app_name
What this does is create the same project folder but also writes the application ID to the application’s configuration file and allows you to have an application name, which is different than the application folder name. For example, to create a project in a folder called myapp but with an application name of Hello, you would issue the following command:
cordova create myapp com.cordovaprogramming.hello Hello
Let me show you an example. I’m going to create a sample application project called Test. To do so, I navigate to the location where I want to create the project and issue the command shown in Figure 4.1.
Notice that the command doesn’t tell you anything about what happened; it simply runs and returns to the command prompt.
Note
All of the Cordova CLI commands operate against the current folder. The create command creates a folder structure for your Cordova projects, and the remaining commands must be issued from within the project folder created by create.
The CLI will run and will create the folder structure shown in Figure 4.2. The folder structure organizes the Cordova project in a way that simplifies the process of using this application across multiple mobile device platforms. Notice that the www folder is separate; this allows you to create a single web application that’s shared across multiple mobile device platforms. I talk more about the web project structure and files in the next chapter.
The merges folder contains web application assets (HTML, CSS, and JavaScript files plus images, videos, and more) that differ across mobile device platforms. If you had, for example, a CSS file with two versions, one for Android and another for iOS, you could use the folder structure in the merges folder to store each file in a mobile device platform–specific location and have the appropriate file copied into the project folder at build time. You would place your Android-specific files (and subfolders) in merges/android and your iOS-specific files in merges/ios.
The platforms folder is used to store a separate folder for each mobile device platform being supported by this application. I talk more about this in the next section. The plugins folder is used to store the source code files for each plugin used by the application. I talk more about this later as well.
In the sections that follow, I describe the remaining CLI commands. The create command creates a new project in a subfolder of the folder from where the command was issued. The remaining commands must be issued from a terminal window pointing within the project folder. In this section, I created a project called test, and the CLI created a folder called test for the project. In order for me to issue CLI commands which manipulate the test project, I must use the cd command to change directory into the test folder before using any of the remaining commands.
Cordova CLI Lazy Loading
If you get an error when creating a project or adding a platform, repeat the process using the –d debug flag and look for an indication of what is happening. If you see a message that says the CLI has the files it needs and is skipping the download, take a look in the folder name mentioned in the error message. If there are no files located in the specified location, you should whack the empty folder and try again.
Platform Management
The project structure we’ve created so far has only a few empty folders plus a web application project. It doesn’t know anything about the different mobile device platform it needs to support. The Cordova CLI provides a platform command that allows you to manage the project files for each of the mobile device platforms your application supports.
Adding Platforms
To add support for a particular mobile device platform to your Cordova application, you must open a terminal window and navigate into the Cordova project folder. Then, to add a project file for a particular mobile device platform, you must issue the following command:
cordova platform add platform_name
Warning
The development tools used to create projects for the particular platform must be installed on the system and visible to the CLI before adding a platform. The CLI uses the platform’s native tools to create a new project, so if the tools are not available to the CLI, the command will not work.
For example, if you wanted to add an Android project to your Cordova application, you would issue the following command from within the Cordova project folder:
cordova platform add android
You can also specify multiple target mobile device platforms in a single command, as shown in the following example:
cordova platform add android blackberry ios
The command doesn’t return anything to the terminal window on success, so unless you see an error reported, the command worked. Let me show you an example. Using the test project we created in the previous section, I must first change to the test directory, then issue the platform command, as shown in Figure 4.4.
If you take a look at Figure 4.5, you’ll see that my project has some new folders and files. In this case, the platforms folder now contains an iOS folder and a complete Xcode project called HelloCordova.xcodeproj. At this point, you could fire up Xcode, open the project, and run the application in the iOS simulator.
The Xcode application project is called HelloCordova because I didn’t specify an app name when I created the project. If I’d created the project using the second form of create (described previously), like this:
cordova create test com.cordovaprogramming.hello Hello
the Xcode project would have been named Hello.xcodeproj.
To add support for Android, I executed the command shown in Figure 4.6.
If you now take a look at the test folder we’ve been working with, you will see that the project’s platforms folder now contains an android folder with a complete Android project inside, as shown in Figure 4.7.
You can open the Android project in a properly configured version of Eclipse (an Eclipse instance with Android Development Tools [ADT] installed) and run and debug the application in the Android emulator. I show you how to do this in Chapter 7, “Android Development with Cordova.”
Listing Platforms
The Cordova CLI provides a mechanism for listing the platforms that are defined within a Cordova project. Simply issue any of the following commands in a terminal window inside of the root folder of a Cordova project:
cordova platforms
cordova platform ls
cordova platform list
The CLI will return a JavaScript Object Notation (JSON) array containing the names of each of the platforms defined within the project:
[ 'android', 'ios', 'blackberry10' ]
You can see an example of this output in Figure 4.8.
This feature isn’t that useful for developers to use directly, since all they have to do is open the project folder and see what subfolders exist within the project’s platforms folder. However, for automated processes, this function is more useful. Since the result is returned as a JSON array, it would be easy for a Node.js application to parse the resulting array, determine if an expected platform were missing and add it.
Removing Platforms
If you decide that you no longer need to support a particular mobile platform for your application, you can remove it by issuing the following command:
cordova platform remove platform_name
You can also use the shortcut rm instead of remove to remove platforms:
cordova platform rm platform_name
So, for my test project, if I want to remove the project files for the iOS project, I would issue the following command:
cordova platform remove ios
You can see the results of this operation in Figure 4.9.
The command doesn’t return anything to the terminal window on success, so unless you see an error reported, the command worked.
Plugin Management
The ability to manage a Cordova project’s plugin configuration is one of the biggest features of the CLI. Instead of manually copying around plugin files and manually editing configuration files, the CLI does it all for you.
Adding Plugins
To use the CLI to add a plugin to an existing project, open a terminal window, navigate to the Cordova project folder, and issue the following command:
cordova plugin add path_to_plugin_files
As an example, to add the Camera plugin to a Cordova application, you could use the following command:
cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git
This connects to the Apache Git repository and pulls down the latest version of the plugin. You can find a list of the core Cordova plugin locations at http://cordova.apache.org/docs/en/3.0.0/guide_cli_index.md.html#The%20Command-line%20Interface.
In general, the plugin git location shown in the previous example uses the following format:
https://git-wip-us.apache.org/repos/asf/cordova-plugin-<plugin-name>.git
where <plugin-name> refers to the short name for the plugin.
The CLI can pull plugin code from most any location; if the system can access the location where the plugin files are located, you can install the plugin using the CLI. If you have plugins installed locally, say, for example, if you were working with a third-party plugin or one you created yourself and the files were stored on the local PC, you could use the following command:
cordova plugin add c:devpluginsmy_plugin_name
Warning
Installing plugins using the CLI is the only supported way to add plugins to a Cordova project. With previous versions of the framework, plugins were added by the developer manually copying files around and modifying configuration files. If you try to use that approach with Cordova 3.0 and beyond, you run the risk of corrupting your Cordova project.
The command doesn’t return anything to the terminal window on success, so unless you see an error reported, the command worked.
Beginning with Cordova 3.1, plugins can be installed directly from the plugin repository just by specifying the plugin name. So, to add the console plugin to your application, you would issue the following command from a terminal window pointing at your Cordova project folder:
cordova plugin add org.apache.cordova.console
The CLI checks the repository for a plugin matching the name specified, pulls down the plugin code, and installs it into your project.
Figure 4.10 shows a Cordova project folder structure after a plugin has been added using the CLI. Notice that each plugin has a unique namespace built using the Reverse-DNS name convention plus the plugin name. All of the Apache Cordova core plugins are referred to by the plugin name added to the end of org.apache.cordova.core. So, for the Camera plugin we just added to the project, you can refer to it via the CLI as org.apache.cordova.core.camera. This approach to plugin naming helps reduce potential for name conflicts across similar plugins created by different organizations.
Plugins have separate folders for the source code for the plugin for each supported mobile device platform. Additionally, some JavaScript files are consumed by Cordova applications in the www folder. There is a lot more to know about plugins; I dig deeper into the plugin project folder structure when I cover plugin development in Chapter 13, “Creating Cordova Plugins.”
Listing Plugins
To view a list of the plugins installed in a Cordova project, open a terminal window, navigate to a Cordova project folder, then issue the following command:
cordova plugins
The CLI will return the list as a JSON array, as shown here:
[ 'org.apache.cordova.core.camera',
'org.apache.cordova.core.device-motion',
'org.apache.cordova.core.file' ]
In this case, the Cordova project has the Cordova core Camera, Accelerator (device-motion), and File plugins installed.
Removing Plugins
To remove a plugin from a Cordova project, open a terminal window, navigate to a Cordova project folder. then issue the following command:
cordova plugin remove plugin_name
You can also use the shortcut rm instead of remove to remove plugins:
cordova plugin rm plugin_name
So, for a project that has the Cordova core File plugin installed, you would remove it from a project by issuing the following command:
cordova plugin remove org.apache.cordova.core.file
The command doesn’t return anything to the terminal window on success, so unless you see an error reported, the command worked.
The CLI will essentially reverse the plugin installation process by removing configuration file entries that point to the plugin plus removing the plugin’s folder from the project’s plugins folder.
Build Management
The CLI has built-in integration with mobile device platform SDKs, so you can use the CLI to manage the application build process.
Prepare
The CLI prepare command copies a Cordova project’s web application content from the www and merges folders into the appropriate platforms folders for the project. This process is described in detail in Chapter 6. You will use this command whenever you make changes to a Cordova web application’s content (in the www or merges folder). The prepare command is called automatically before many of the operations described throughout the remainder of this chapter.
To use the prepare command, open a terminal window, navigate to a Cordova project folder, then issue the following command:
cordova prepare
This copies the web application content into the appropriate folders for each of the mobile device platforms that have been added to the project.
To prepare a specific platform’s files, use the following command:
cordova prepare platform_name
So, to prepare the Android platform folder, use the following command:
cordova prepare android
The command doesn’t return anything to the terminal window on success, so unless you see an error reported, the command worked.
Compile
In Figure 4.7, you can see that there’s a cordova folder in each platform’s folder structure. Within that folder are platform-specific build scripts used to compile a native application for that platform. The compile command initiates a compilation process by calling the build script for one or more mobile platforms.
To use the compile command, open a terminal window, navigate to a Cordova project folder, then issue the following command:
cordova compile
To compile a specific platform’s native application, use the following command:
cordova compile platform_name
So, to compile the Android version of an application, use the following command:
cordova compile android
The command doesn’t return anything to the terminal window on success, so unless you see an error reported, the command worked.
Build
The build command is similar to compile except that it first calls prepare before calling compile.
To use the build command, open a terminal window, navigate to a Cordova project folder, then issue the following command:
cordova build
To build a specific platform’s native application, use the following command:
cordova build platform_name
So, to build the Android version of an application, use the following command:
cordova build android
The command doesn’t return anything to the terminal window on success, so unless you see an error reported, the command worked.
Running Cordova Applications
The CLI has built-in integration with mobile device platform simulators, so you can launch Cordova applications directly onto simulators or physical devices. Chapters 7 through 10 provide more detailed information about the simulators, how to configure and launch them, as well as what is required to work with physical devices from the CLI. The following sections provide a high-level overview of the relevant commands.
Emulate
The CLI emulate command automates the process of building an application and deploying it onto a mobile device simulator. The command first prepares the application, executes the build process, then deploys the resulting native application package to the simulator.
To run a Cordova application on the default simulator for each of the platforms configured in the project, issue the following command:
cordova emulate
To emulate the application on a single device platform emulator, Android for example, you would issue the following command:
cordova emulate android
The CLI is supposed to launch the simulator automatically for you; this works well for iOS but doesn’t work for BlackBerry, and I had mixed results trying this on Android.
For the BlackBerry platform, additional steps must be followed to define simulator targets for the emulate command; refer to Chapter 8, “BlackBerry 10 Development with Cordova,” for additional information.
Run
The CLI run command automates the process of building an application and deploying it onto a physical device. The command first prepares the application, executes the build process, then deploys the resulting native application package to a connected device.
To run a Cordova application on a physical device for each of the platforms configured in the project, issue the following command:
cordova run
To run the application on a single device, Android for example, you would issue the following command:
cordova run android
For the BlackBerry and Windows Phone 8 platforms, additional steps must be followed before you can run an application on a device. Refer to Chapter 8 for additional information on configuring a BlackBerry device and Chapter 10, “Windows Phone 8 Development with Cordova,” for Windows Phone 8.
Serve
When working with a mobile web application, many developers find that it’s better to test the application in a desktop browser before switching to the mobile device. This is especially important when it comes to Cordova applications because an extra packaging process has to happen before the application can be run on a device or simulator.
The CLI includes a serve command, which a developer can use to launch a local web server that hosts a particular platform’s web content. It doesn’t expose any of the Cordova APIs to the browser, so all you can really test using this option is your web application’s UI. You must issue the CLI prepare command before launching the server to make sure your web content is up to date.
To use the serve command, open a terminal window, navigate to a Cordova project folder, then issue the following command:
cordova serve platform_name
To serve up a Cordova project’s Android web application content, you would issue the following command:
cordova serve android
Figure 4.11 shows the serve command in action. Once the command loads, it will show you what URL you must use to access the web server. Simply open your browser of choice and navigate to the specified URL to access the application content.
When running this process on Microsoft Windows, you may receive a security warning similar to the one shown in Figure 4.12. You need to click the Allow access button to allow the web server to start.
By default, the server will respond to port 8000, as shown in Figure 4.11. If you want to use a different port, you can pass the port number to the CLI, as shown in the following example:
cordova serve platform_name port_number
So, for the Android example shown previously, to serve the Android platform’s content on port 8080, you would use the following command:
cordova serve android 8080
Wrap-Up
In this chapter, I showed you how to utilize the Cordova CLI to manage your Cordova application projects. The capabilities provided by the CLI dramatically simplify the cross-platform development process and managing your Cordova application’s plugin configuration.
In the next chapter, I discuss the structure of a Cordova application. In Chapter 5, I describe the process of building and debugging your Cordova applications.