Tue 03 November 2015
By Alice Heaton

Setting up a Cordova development environment in Ubuntu

While there are many guides on setting up Apache Cordova for Android development on Ubuntu, none seemed to cover all the issues I encountered - it took a combination of resources to get there. I decided to write how I went about setting this up, and the issues I encountered along the way.

Note that this was done on Ubuntu 14.04.

Download the Android SDK

The Android SDK is Google's development platform for Android applications. Even though we're going to do cross platform development using Cordova we still need to install the SDK so Cordova can build and deploy the Android version of the application.

The Android SDK can be downloaded directly from Google. I install it under /usr/local:

cd /usr/local
sudo wget http://dl.google.com/android/android-sdk_r24.3.4-linux.tgz
sudo tar -xzf android-sdk_r23.3.4-linux.tgz
sudo chmod ugo+x /usr/local/android-sdk-linux/tools/android

You should then update the SDK to the latest version, and download the Android APIs for the version you want to build for. You can do this using the Android SDK provided GUI tool:

gksudo /usr/local/android-sdk-linux/tools/android update sdk

By default this will install the latest version of the tools, and the latest version of the Android APIs (You'll need to accept a number of licences). If you want to develop for older versions of Android, make sure to select the APIs accordingly.

You will need the tools and platform-tools folders in your path. I add this to my ~/.bashrc:

PATH="$PATH:/usr/local/android-sdk-linux/tools:/usr/local/android-sdk-linux/platform-tools"

Install Cordova, and create a skeleton application

The easy way is to use npm, the Javascript package manager, which you may need to install first:

sudo apt-get install npm

You can then install Cordova globally:

sudo npm install -g cordova

Note that if you want to run on older Android versions (eg. 2.3), you will need an older version of Cordova. So for Android 2.3 support, you would want to install:

sudo npm install -g "cordova@4.3.0"

Finally create a skeleton project:

cd ~/projects
cordova create myapp com.example.myapp MyApp

Where myapp is the folder name, com.example.myapp the reverse domain name that uniquely identifies your application, and MyApp the actual name of the application. This will create multiple folders under ~/projects/myapp:

  • hooks: Initially empty, you can add scripts to customize cordova commands. See the README in the folder;
  • platforms: This contains the files needed to build the application for each target environment, and is populated when you run commands such as cordova platform add android (see next section);
  • plugins: This contains your cordova plugins, and is populated when you run commands such as cordova plugin add org.apache.cordova.device (see next section);
  • www: This is where your application lives! It all starts with an index.html file, and from there on it's up to you!

I exclude both the platforms and plugins folders from version control. I have not had the need to edit any of their content, and they can easily be generated by invoking the appropriate cordova commands. If you were to edit some files under platforms, you would probably want to exclude some of it's sub-folders, as build binaries go there.

So my .gitignore includes:

platforms/
plugins

Add Android platform to your project

You add the android platform by doing:

cd ~/projects/myapp
cordova platform add android

You also use the cordova command line to add plugins by running, for example:

cordova plugin add org.apache.cordova.device

There a two basic plugins that are recommended for all projects:

  • The device plugin, org.apache.cordova.device, adds a global device object which describes the device's hardware and software;
  • The console plugin, org.apache.cordova.console, improves the native console.log calls.

Start the adb server

The Android SDK runs a server used to connect to attached Android devices - the Android Debug Bridge known as adb.

The adb server must be run as root. However Cordova commands that require it will launch it as the current user - causing cryptic errors such as "no target specified" when you try to run the application.

To prevent this from happening you must first launch the adb server as root. You can start the server as a service at every boot, or just start it manually at the beginning of every session:

sudo adb start-server

If you forgot to start it, you must stop it and re-start it:

sudo adb kill-server
sudo adb start-server

Check it's working

We're ready to check if it's working! Edit the index file to put a success message:

cd ~/projects/myapp/www
echo '<html><body>success</body></html>' > index.html

You will need to enable debug mode on your phone - depending on your Android version this may require finding some hidden menu items! See the tutorial at https://www.kingoapp.com/root-tutorials/how-to-enable-usb-debugging-mode-on-android.htm.

This done, you just need to plug your phone in and run:

cordova run android

Tada! Well, hopefully, Tada. It's possible you'll encounter other issues - it took me a bit of research to get this far. Many other people have been there before, so with a bit of online search you should be able to find the solution to any problem.

Debuging

You can view the logs from the phone by running:

adb logcat