Ubuntu Platform Guide
This guide shows how to set up a development environment for creating Cordova applications for Ubuntu.
You will need an Ubuntu system for building applications, either running natively or in a virtual machine. You will also need an Ubuntu phone for testing your application, though an emulator can be used for basic verifications.
Development Platform Requirements
Minimum and Recommended Versions
Developing Cordova apps requires a system running Ubuntu.
The recommended environment is Ubuntu 16.04 LTS, running NodeJS 4.2.x and NPM 2.15.x.
Packages are still available for systems running the previous LTS release (14.04) but some components like NodeJS or phablet-shell may not support all of the latest options.
The target environment is an Ubuntu phone, supporting at least the ubuntu-sdk-api-15.04 framework. All phones on the market, or development images, support that framework by default.
The cordova-ubuntu platform support code requires at least cordova-cli 4.3.1. This is the minimum and recommended version at the time of this writing. cordova-ubuntu 4.3.x releases are all compatible with that tool release.
For the latest information on Cordova app support for Ubuntu runtime platforms, see wiki.ubuntu.com/Cordova.
Installing the Development Environment
Install Ubuntu
Installation images of Ubuntu 16.04 LTS are available at http://www.ubuntu.com/download
The simplest option is to download an Ubuntu Desktop image.
In any case, the Debian packaging system will ensure that all underlying dependencies for the development environment will be installed. This lets you also install a build environment from an Ubuntu server installation as well.
Ubuntu Virtual Machine (optional)
Ubuntu can also be used in a virtual machine.
You can get an Ubuntu instance on all of the leading public clouds. In fact, Ubuntu is the most popular cloud operating system (http://www.ubuntu.com/cloud/public-cloud). Running in the cloud will let you build your Cordova application. However you will still need to connect a local instance to a phone via USB for testing your app.
You can also install Ubuntu in local VM, with Virtualbox, VMWare or Parallels on either Windows or Mac OS. That configuration lets you re-direct a USB port inside the virtual machine, to let the Ubuntu build system access the Ubuntu phone hardware and install the app for testing.
Refer to the documentation for either your public cloud of choice, or the local virtual machine for the details of the installation procedure.
Once you have a basic Ubuntu VM set up, you can install the rest of the required elements below.
Node and NPM
Ubuntu 16.04 LTS comes with the required versions of both NodeJS and NPM. To install simlpy do:
$ sudo apt-get install nodejs npm $ node -v v.4.2.6 $ npm -v 2.15.6
Cordova CLI
The Cordova command line interface can be installed either via npm, or you can use a pre-packaged version available specifically for Ubuntu.
The recommended installation path is to use the pre-packaged version for Ubuntu, as it generally contains Ubuntu specific fixes which may not all have been merged upstream.
Installing the cordova-cli deb package requires to:
- Add the Ubuntu Cordova Personal Package Archive to your Ubuntu system
- Install the cordova-cli package (and its dependencies)
$ sudo apt-add-repository ppa:cordova-ubuntu/ppa $ sudo apt-get update $ sudo apt-get install cordova-cli
Add an Ubuntu "click chroot"
The build environment needs to be separated from the developer's environment, to prevent unwanted side effects and provide a clean, repeatable process.
Ubuntu devices currently use the click packaging system.
To produce click packages, a "click chroot" is required. It is a separate build environment designed to produce binaries, by having a build tools and dependencies contained inside a chroot.
Generally, a click chroot hosts cross-compilation tools which can produce binaries for a different architecture (like armhf) than the one of the developer's system (generally x86).
Last, the click chroot will need to be provisionned with libraries, or more generally "frameworks", corresponding to the target environment.
Ubuntu devices will support the ubuntu-sdk-15.04 framework or later versions.
Create a click chroot environment
$ sudo apt-add-repository ppa:ubuntu-sdk-team/ppa $ sudo apt-get update # this will create a clean click chroot build environment sudo apt-get install click-dev phablet-tools ubuntu-sdk-api-15.04
Add build dependencies for Cordova
# add build dependencies inside the click chroot sudo click chroot -a armhf -f ubuntu-sdk-15.04 install cmake libicu-dev:armhf pkg-config qtbase5-dev:armhf qtchooser qtdeclarative5-dev:armhf qtfeedback5-dev:armhf qtlocation5-dev:armhf qtmultimedia5-dev:armhf qtpim5-dev:armhf libqt5sensors5-dev:armhf qtsystems5-dev:armhf
Ubuntu IDE (optional)
You may also want to install the Ubuntu QtCreator development environment. See developer.ubuntu.com for more info. (The QtCreator SDK is not required to add Ubuntu platform support to your Cordova app.)
Project Workflow
To test your installation, or simply to start developing an application, you can follow the steps below.
Create a project
Creates an app in a hello directory whose display name is HelloWorld:
$ cordova create helloworld helloworld.ubuntudeveloper HelloWorld $ cd hello $ cordova platform add ubuntu
Note that Ubuntu applications use a pair . as a naming convention.
Add a Plugin
$ cordova plugin add cordova-plugin-camera
Build for Ubuntu devices
$ cordova build --device
You can see detailed build logs with the following options:
$ cordova -d build --device -- --verbose
You can build your app for a different target framework by specifying the option below:
$ cordova -d build --device -- --framework=ubuntu-sdk-16.04
Note that for the latter to work, you will need to have a corresponding click chroot installed on your build system.
Run the App on an Ubuntu device
$ cordova run --device
This will:
- build the app for the device target
- package it using the click packaging system
- transfer the app on the device
- stop the app if it was already running
- install the app
- start the app
Debugging
You can enable chrome devtools support to debug your app, by adding the --debug flag:
$ cordova run --device --debug
Then simply connect to the URL mentioned in the logs.
Publishing your app
Once you have finished developing and testing your app, you can publish it on the Ubuntu App Store.
Generate and verify the package
Your app is already packaged in a format compatible with the app store. Just find the .click package generate by the cordova-ubuntu build system:
$ cordova build --device $ find -name "*.click"
You can manually verify that the package passes all verification steps enforced by the Ubuntu App Store system, by using the click-reviewer-tools:
$ click review -v <click file>
Note: this step is done automatically by the build system as well.
Sign up and upload to the app store
You need to first create a free developer account on the Ubuntu App Store.
Then you will be able to upload your package to the store and make it available to all users of Ubuntu devices.
The full process is documented online at https://developer.ubuntu.com/en/publish/
Please login to continue.