cc by-sa flurdy

Cordova (Phonegap) within Vagrant for Android

Started: Janurary 2015. Last updated: 15th Jan 2015.

Purpose

Cordova is cross platform for building applications for multiple smartphones OSes such as Android and iPhone's IOS. It ustilises mostly HTML, CSS and Javascript and is easy to pick up.

Cordova is the open source version of Phonegap, and is all you need when starting out developing apps. Phonegap do provide some nice bells and whistles when you are really advanced, but I am nowhere needing that yet.

Vagrant provides headless virtual machines for development environment.

Android provide a free development SDK for many OSes to build applications for Android based mobiles. At a later stage it would make sense to also initially test your application with Apple's IOS devices, but it is more restrictive in setting up initially. Due to market share the other platforms (Windows, Symbian, etc) can wait.

Together they provide an environment to develop mobile apps locally that is separate from your actual machine.

Vagrant Install

You need to install a Virtual Machine provider first. I always use VirtualBox. You can install via packages from VirtualBox's and Vagrant's download pages.

Vagrant on OSX

If not direct from downloads you can install via Brew and Cask.

osxhost$ brew cask install virtualbox; osxhost$ brew install vagrant

OSX X11

If you are running Mac OSX and not Linux then you need to install the X11 support for OSX. They are no longer installed by default but Apple provide a simple install via XQuartz. It allows X11 applications from a Vagrant VM to be displayed in OSX.

osxhost$ wget http://xquartz.macosforge.org/downloads/SL/XQuartz-2.7.7.dmg; osxhost$ open XQuartz-2.7.7.dmg

You need to restart your machine for the Xserver to work in your OSX session.

Vagrant on Ubuntu

If not direct from downloads you can install via apt-get packages. Note these packages might be slightly older.

ubuntuhost$ sudo apt-get install virtualbox vagrant

Make sure you have the multiverse repository enabled.

Vagrant plugins

Optional.

anyhost$ vagrant plugin install vagrant-vbguest; anyhost$ vagrant plugin install vagrant-vbox-snapshot

Vagrant setup

anyhost$ mkdir cordova-vagrant && cd cordova-vagrant; anyhost$ vagrant init ubuntu/trusty64

This downloads a Vagrant Ubuntu 14.04 image, and initialises a Vagrant instance for you.

Edit the Vagrantfile it created in your folder.

anyhost$ vi Vagrantfile; # -*- mode: ruby -*-
# vi: set ft=ruby :

VAGRANTFILE_API_VERSION = "2"

Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|

config.vm.box = "ubuntu/trusty64"

config.vm.hostname = "cordova"

config.vm.box_check_update = false

if Vagrant.has_plugin?("vagrant-vbguest") then
config.vbguest.auto_update = false
end

## Most likely you want to edit files locally in
## an editor, but out of scope for this howto
# config.vm.synced_folder "../cordova-app", "/home/vagrant/cordova-app"

config.vm.provider "virtualbox" do |vb|
vb.customize ["modifyvm", :id, "--memory", "2048"]
end

config.ssh.forward_agent = true
config.ssh.forward_x11 = true

end

Then start up and log into the new vagrant instance.

anyhost$ vagrant up && vagrant ssh

Dependencies

On this new Ubuntu inside Vagrant install the support for PPA repositories and 64 bit to 32 bit support as Android SDK is in 32bit.

vagranthost$ sudo apt-get update && sudo apt-get upgrade && sudo apt-get autoremove; vagranthost$ sudo apt-get install -yq python-software-properties; vagranthost$ sudo apt-get install -yq lib32z1 lib32ncurses5 lib32stdc++6

Java install

Add the ppa repository for Java by webupd8team, and install Java 7 including accepting the Oracle Java license.

vagranthost$ sudo add-apt-repository ppa:webupd8team/java; vagranthost$ sudo apt-get update; vagranthost$ sudo apt-get install oracle-java7-installer oracle-java7-set-default; vagranthost$ echo "JAVA_HOME=/usr/lib/jvm/java-7-oracle" >> ~/.bashrc;

Test if it installed ok.

vagranthost$ java -version

Ant install

Ant is in Ubuntu's repositories but usually brings along too much dependency bagage, so I prefer the direct download version.

vagranthost$ wget http://www.mirrorservice.org/sites/ftp.apache.org//ant/binaries/apache-ant-1.9.4-bin.tar.gz; vagranthost$ tar xzf apache-ant-1.9.4-bin.tar.gz; vagranthost$ sudo mv apache-ant-1.9.4 /opt/apache-ant; vagranthost$ echo "ANT_HOME=/opt/apache-ant" >> ~/.bashrc; vagranthost$ echo 'PATH=$PATH:$ANT_HOME/bin' >> ~/.bashrc; vagranthost$ source ~/.bashrc;

Test if it installed ok.

vagranthost$ ant -version

Node.js install

Node.js is yet another download.

vagranthost$ wget http://nodejs.org/dist/v0.10.35/node-v0.10.35-linux-x64.tar.gz; vagranthost$ tar xzf node-v0.10.35-linux-x64.tar.gz; vagranthost$ sudo mv node-v0.10.35-linux-x64 /opt/node; vagranthost$ echo "NODE_HOME=/opt/node" >> ~/.bashrc; vagranthost$ echo 'PATH=$PATH:$NODE_HOME/bin' >> ~/.bashrc; vagranthost$ source ~/.bashrc;

Test if it installed ok.

vagranthost$ node --version; vagranthost$ npm --version

Android install

Find the link to the latest Android SDK for Linux.

vagranthost$ wget http://dl.google.com/android/android-sdk_r24.0.2-linux.tgz; vagranthost$ tar xzf android-sdk_*.tgz; vagranthost$ sudo mv android-sdk-linux /opt/android-sdk; vagranthost$ echo "ANDROID_HOME=/opt/android-sdk" >> ~/.bashrc; vagranthost$ echo 'PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools' >> ~/.bashrc; vagranthost$ source ~/.bashrc;

Test if it installed ok.

vagranthost$ android -h

Android update

Updating the SDK is how to download all the platform files for each version of Android. You don't have to download all of them as Cordova only supports older versions with more than 5% market share and only the tools they need.

First to see which are available. Note the ids so which can be used to install each section.

vagranthost$ android list sdk --no-ui --all --extended

Then we apply the filters relevant for us, split across a few commands for readability. You will need to accept a few Android license prompts.

vagranthost$ android update sdk -u -a --filter "tools,platform-tools,build-tools-21.1.2"; vagranthost$ android update sdk -u -a --filter "android-21,android-20,android-19"

Android device

You need an Android emulated device (or more) to test you applications on. These are installed via the same update command and then created afterwards.

vagranthost$ android update sdk -u -a --filter "sys-img-armeabi-v7a-android-21";

You need to find the target id for the device image(s) just downloaded.

vagranthost$ android list targets;

Note the id of the target with a Tag/ABIs that does not say no ABIs, use that one. Sometimes you also have to specify the Abi if there are several images (ARM,x86,etc) available per Android platform version.

vagranthost$ android create avd \
--name cordovakitkat --target android-21 --abi default/armeabi-v7a

Cordova install

This often but not always will display some dependency not found errors, but it should still install and for me has worked as expected.

vagranthost$ npm install -g cordova;

Test if it installed ok.

vagranthost$ cordova --version

Project setup

Create project

Lets create the standard Hello World.

vagranthost$ cordova create hello com.example.hello HelloWord;

First argument hello is the name of the folder.

Second argument com.example.hello is the namespace / package name.

Third argument HelloWorld is the name of the application.

Add platform

These define which platform the app will build for. Initially we will just focus on Android. Later you can expand these once everything works.

vagranthost$ cd hello; vagranthost$ cordova platform add android; vagranthost$ cordova platforms list

Build application

Edit one page to show our changes are displayed later. Then build the application.

vagranthost$ sed -i 's/Ready/Wazzup/' www/index.html; vagranthost$ cordova build

Run emulator

This should launch the emulator on your local machine.

vagranthost$ cordova emulate android

It will take some time, especially on initial launch. It will need to create the device, boot the OS, log in and then finally install the application. So please wait.

Note: I often on a fresh machine/project have to run this command 2-3 times including the waiting before it works as expected.

Once fully loaded and app has been installed there should be a Cordova icon on the first page.

If you see the error below your X11 over SSH is not configured correctly.

SDL init failure, reason is: No available video device

Voila!

That is it. You can now iterate over your application, adding Cordova features and adding more platforms.

What next

There is a follow up howto, Cordova application with Ratchet and Handlebars. A guide on creating a simple cross platform smartphone application.

Another further howto might build on these to show basic database, server APIs and 3rd party API integration and synchronisation.

This howto should also be extended to describe IOS as a platform as well. Though that might be difficult inside a VM as Apple insist on OSX as OS.

With this as a working standardised Vagrant set up, doing a simular job for a Docker image should be possible.

References

Feedback

Please fork and send a pull request for to correct any typos, or useful additions.

Buy a t-shirt if you found this guide useful. Hire Ivar for short term advice or long term consultancy.

Otherwise contact flurdy. Especially for things factually incorrect. Apologies for procrastinated replies.