Ubuntu Platform Guide - Apache Cordova about:reader?url=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fcordova.apache...

cordova.apache.org

Ubuntu Platform Guide - Apache

Cordova
7–9 minutes

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

1 of 7 12/15/23, 18:41
Ubuntu Platform Guide - Apache Cordova about:reader?url=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fcordova.apache...

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.

2 of 7 12/15/23, 18:41
Ubuntu Platform Guide - Apache Cordova about:reader?url=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fcordova.apache...

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:

1. Add the Ubuntu Cordova Personal Package Archive to your

Ubuntu system

2. Install the cordova-cli package (and its dependencies)

$ sudo apt-add-repository ppa:cordova-

ubuntu/ppa
$ sudo apt-get update

3 of 7 12/15/23, 18:41
Ubuntu Platform Guide - Apache Cordova about:reader?url=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fcordova.apache...

$ 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

4 of 7 12/15/23, 18:41
Ubuntu Platform Guide - Apache Cordova about:reader?url=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fcordova.apache...

# 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.

5 of 7 12/15/23, 18:41
Ubuntu Platform Guide - Apache Cordova about:reader?url=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fcordova.apache...

Add a Plugin

$ cordova plugin add cordova-plugin-camera

Build for Ubuntu devices

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

This will:

1. build the app for the device target

2. package it using the click packaging system

3. transfer the app on the device

4. stop the app if it was already running

5. install the app

6. start the app

Debugging

You can enable chrome devtools support to debug your app, by

adding the --debug flag:

$ cordova run --device --debug

6 of 7 12/15/23, 18:41
Ubuntu Platform Guide - Apache Cordova about:reader?url=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fcordova.apache...

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/

7 of 7 12/15/23, 18:41