This page explains how to customize an image-based update image and contains the status of various hacks needed to make it work (and a path to get them to be non-hacks).

Installation

The Customized images are installed simply by passing a channel name to phablet-flash. There are currently 4 supported customization channels:

• devel-customized: The stable image with customization bundle (Ringtel)
• devel-proposed-customized: The latest proposed image with customization bundle (Ringtel)
• devel-customized-generic: The stable image with a non-branded customization bundle
• devel-proposed-customized-generic: The latest proposed with a non-branded customization bundle

To install, simply plug in a phone and run

phablet-flash ubuntu-system --channel <one-of-the-above-channel-names>

The Customization Tarball

Builds

• Savilerow - test-bed for changes: https://jenkins.qa.ubuntu.com/job/savilerow-trusty/

Making changes to the tarball

Our main branch of customizations lives in:

bzr branch lp:savilerow

After merging a change, a new tarball is automatically generated by jenkins, and can be downloaded here:

• jenkins artifacts

Building the tarball locally

Any merges going through are required to be tested, which requires building the tarball manually. To build the tarball, simply cd into the savilerow root and run

tar Jcvf ../custom.tar.xz system/

and then follow the installation instructions for unsigned images.

How Customization Works

This section explains the contents of the customization tarball.

Copying into ~phablet

Any file in /system/custom/home is copied wholesale into /home/<user>. This is done in the initrd. The contents of the tarball should be owned by root:root for this to work.

Files copied

• .config/ubuntu-ui-toolkit/theme.inif: Sets the App theme
• .config/webbrowser-app/settings.conf: Sets the browser homepage
• Pictures/* : Sample Pictures
• Music/*: Sample Music
• Videos/*: Sample Videos
• .local/share/webbrowser-app/bookmarks.sqlite : Web Browser bookmarks

Copying is done only once, and is controlled by the presence of /home/<user>/.customized. If you want it to happen again, then remove that file.

This copying is done by an initrd script called "touch". The code is in lp:initramfs-tools-ubuntu-touch

Hooks in ubuntu-touch-customization-hooks

The ubuntu-touch-customization-hooks package (referred to as the hooks package) is a main Ubuntu package which provides upstart jobs that the customization bundle uses. The code is hosted at lp:ubuntu-touch-customization-hooks.

Jobs

• A session job that sets assorted dconf variables. This is done to set XDG_DATA_DIRS, a themes dir, and the path to DCONF database and profile.

• A session job that sets the welcome screen background via a dbus call to AccountService

• A system job that sets the dconf environment variables and allows us to point at a system-level dconf db (background) that lives in /custom/etc/dconf.

Customizing Settings with dconf

Before reading this section, you should be familiar with dconf databases, keys, and locks

dconf is the most common way to change settings for an Ubuntu image. In order to customize a setting, you will need to change the key file. If you want the setting to be read-only you will need to add a lock file. The layout of these files is as follows:

• system/custom/etc/dconf_profile - the dconf profile that points at the custom db, you should not need to change this, although we can do a hierarchy of settings with this profile if needed.

• system/custom/etc/dconf - this is the area that will be mounted as writable in the image. Do not place any customization stuff here, it will not be field updateable

• system/custom/etc/dconf_source/db/custom.d/custom.key - this is the file where you customize your dconf settings. Follow the format in the file or read the background wiki page at the top of this section.
• system/custom/etc/dconf_source/db/custom.d/locks/custom.lock - this is the file where you add any locks that are needed.

When the phone boots, dconf update is run to update the customdb, however, because we have to copy the files from dconf_source to the writable folder of dconf, we only do this once. If you want dconf update to run again, then you need to remove /custom/etc/dconf/.updated and reboot. You can also run it manually by following the pre-session.d job that runs dconf update (see below).

Updated dconf keys

wallpapers/etc

For files that need to be added to the image, it was decided to mirror the ubuntu filesystem layout as much as possible. These files live in /system/custom/usr

Demo infographics

For example infographics, we drop a binary called demometrics into /custom/infographic. Along with this we drop a data.txt file which contains the strings that demometrics needs to use. An upstart job is dropped into /home/phablet/.cache/upstart and that job runs demometrics /custom/infographic/data.txt. A random value between 2 and MAX is selected for each day and each category. The format of the data file is as follows

category:N <something>:No something today:MAX

Testing

Infographic data is stored in /var/lib/usermetrics/usermetrics4.db. If you plan on testing it, you need to remove this file after making changes so that new data is loaded.

Custom Click Apps

The click apps included in the bundle are already preinstalled to /custom/click. That means they don't need to be installed or registered when the tarball is unpacked. To add a click app to the tarball, the easiest way to do so is to the following:

adb push /home/phablet/whatever.click
adb shell
cd /home/phablet
click install --root=/custom/click --all-users --force-missing-framework <click-name>.click
click register --all-users <click-name> <click-version>
tar zcvf custom-click.tgz /custom/click
exit
adb pull /home/phablet/custom-click.tgz
tar -C /path/to/savilerow/system/custom zxvf custom-click.tgz

To Do

• Look into custom power policies (cwayne)
• Track conversion of UITK theming from file in ~ to GSettings (cwayne + zsombi)