Merge lp:~achiang/savilerow/tutorial into lp:~savilerow-team/savilerow/trunk-1.0

[Alex Chiang]

Write a tutorial for someone just getting started with savvy.

I tested this by following my own instructions:

- clean install of latest image, with -wipe=true
- clean bzr branch of lp:savilerow
- then followed the tutorial steps exactly

Ended up with a successfully customized wallpaper.

Rendered html is on chinstrap, as always.

[Chris Wayne (cwayne)]

I think the building and installing should be scripted, but I think this a fine start (we can always change it later once it's scripted). +1

review: Approve

[Alex Chiang (achiang)]

Agreed. We can create something like phablet-test-savvy or something.

=== modified file 'doc/architecture.rst'
--- doc/architecture.rst	2014-01-24 12:39:15 +0000
+++ doc/architecture.rst	2014-02-07 23:37:04 +0000
@@ -1,6 +1,6 @@
-==================
-Image Architecture
-==================
+=========================
+Ubuntu Image Architecture
+=========================
 
 An overview of the Ubuntu Touch disk image design is presented here.
 An understanding of the image components, how they are organized,

=== modified file 'doc/usage.rst'
--- doc/usage.rst	2014-01-25 05:40:25 +0000
+++ doc/usage.rst	2014-02-07 23:37:04 +0000
@@ -1,29 +1,49 @@
-===========
+======================
+Quick Start + Tutorial
+======================
+
+To get started with the Savvy architecture, follow the quick start
+instructions. This procedure will install the example customized image
+on your device and allow you to get a sense for the types of
+customizations permitted by the Savvy API.
+
+After experimenting with the sample customizations, you will probably
+want to experiment with your own customizations. The tutorial section
+explains how to do so.
+
 Quick Start
 ===========
 
-To quickly get started with the Savvy architecture, follow the
-automated installation instructions. This procedure will install the
-example customized image on your device and allow you to get a sense
-for the types of customizations permitted by Savvy.
-
-After experimenting with the sample customizations, you will
-probably want to experiment with your own customizations. The second
-section explains how to do so.
-
-Automated Installation
-======================
-
-This procedure requires the use of ``phablet-flash`` tool and a
-supported device. Once both prerequisites are met, simply issue::
+This procedure will install Canonical's example customization package
+onto a device. After installing the example customizations, you will be
+able to explore how the Savvy API can be used to change the look, feel,
+and behavior of Ubuntu Touch to suit your requirements.
+
+It requires:
+
+  * `device supported by Ubuntu Touch`_, such as the Nexus 4
+  * `phablet-flash`_ - tool to install Ubuntu Touch on your device
+
+Once both prerequisites are met, simply issue::
 
   phablet-flash ubuntu-system --channel devel-customized
 
 The command will install the sample customizations on the latest
 version of Ubuntu Touch, on a supported device.
 
-Making modifications
-====================
+**Note:** the quick start assumes you have already been able to
+successfully install your device with the default Ubuntu image. If you
+encounter difficulty, please refer to the `installation instructions`_.
+
+.. _`device supported by Ubuntu Touch`: https://wiki.ubuntu.com/Touch/Install/#Supported_devices_and_codenames
+
+.. _`phablet-flash`: https://wiki.ubuntu.com/Touch/Install#Step_1_-_Desktop_Setup
+
+.. _`installation instructions`: https://wiki.ubuntu.com/Touch/Install
+
+
+Tutorial
+========
 
 Obtaining the code
 ------------------
@@ -36,29 +56,138 @@
 
 The project layout is very straightforward:: 
 
-  doc/  system/  tests/  ubuntu_command
+  doc/  src/  tests/
 
 As you can see:
 
   * ``doc/`` contains this documentation
-  * ``system/`` contains the example customization code
+  * ``src/`` contains the example customization code
   * ``tests/`` contains the test suite
-  * ``ubuntu_command`` is used by the build system and should not be modified
 
-The ``system/`` directory will be of greatest interest, as it
+The ``src/`` directory will be of greatest interest, as it
 demonstrates all the possible customizations permitted by the Savvy
 API.
 
+
+Making a modification
+---------------------
+
+In this example, we will set a different default wallpaper. Looking in
+the directory ``src/system/custom`` we will modify the following files::
+
+  .
+  ├── etc
+  │   ├── dconf
+  │   ├── dconf_profile
+  │   └── dconf_source
+  │       └── db
+  │           └── custom.d
+  │               ├── custom.key
+  │               └── locks
+  │                   └── custom.lock
+  └── usr
+      └── share
+          └── backgrounds
+              └── ringtel_wallpaper_plain.png
+
+You may remove all other files and directories in ``src/system/custom``.
+
+The first step is to add a new wallpaper. In this example, we will
+assume the filename is ``wallpaper.jpg``. Copy the file to
+``usr/share/backgrounds``::
+
+  └── usr
+      └── share
+          └── backgrounds
+              ├── ringtel_wallpaper_plain.png
+              └── wallpaper.jpg
+
+Next, you will need to edit ``custom.key`` and ``custom.lock``::
+
+  $ cat etc/dconf_source/db/custom.d/custom.key 
+  # if the keys have uppercase letters, make them lowercase here, for
+  # example com.canonical.Unity.Lenses -> com/canonical/unity/lenses
+  
+  [org/gnome/desktop/background]
+  picture-uri='file:///custom/usr/share/backgrounds/wallpaper.jpg'
+
+The contents of ``custom.lock`` should be::
+
+  $ cat etc/dconf_source/db/custom.d/locks/custom.lock 
+  /org/gnome/desktop/background/picture-uri
+
+That's it! Now we are ready to test the results.
+
+**Note:** the provided sample wallpaper is ``png`` format, but in this
+example, we are using an image in ``jpg`` format. Both file formats are
+supported.
+
+
 Building the tarball
 --------------------
 
-Modifying Savvy code is as simple as editing files in the
-``system/`` directory. After making changes there, you must rebuild
-the tarball::
-
-  tar -Jcvf ../custom.tar.xz system/
+After making changes above, we will rebuild the tarball from the
+top-level directory::
+
+  $ pwd
+  /home/ubuntu/Projects/savvy/tutorial
+
+  $ ls
+  doc/  src/  tests/
+
+  $ tar -Jcvf custom.tar.xz -C src/ system/
+
+  $ ls
+  custom.tar.xz  doc/  src/  tests/
 
 This command will produce a new, unsigned tarball in the parent
-directory. To install it, please follow the following instructions_.
-
-.. _instructions: https://wiki.ubuntu.com/Touch/Customization/Installation#Installing_an_unsigned_image
+directory.
+
+
+Installing the tarball
+----------------------
+
+The Ubuntu Image Architecture requires that all tarballs installed on
+the system must be signed.
+
+In this tutorial, we have not signed the new custom tarball so we must
+use a developer shortcut which does not check for GPG signatures.
+
+  **THIS SHOULD NOT BE USED FOR DAILY USERS.**
+  
+  It is only to be used for testing an unreleased recovery image.
+
+Download the recovery images and ubuntu_command from here:
+
+  http://people.canonical.com/~cwayne/touch/custom-recovery/
+
+To install the recovery::
+
+  adb reboot bootloader
+  fastboot flash recovery ~/Downloads/mako-recovery.img
+  fastboot reboot
+
+Now to install the customization tarball.
+
+**Note:** ensure that you have the ``ubuntu_command`` from the above
+link!::
+
+  adb push custom.tar.xz /cache/recovery
+  adb push ~/Downloads/ubuntu_command /cache/recovery
+  adb reboot recovery 
+
+
+Finishing up
+------------
+
+After rebooting the device, you should have a new background.
+
+There are many more customizations possible with the Savvy API, and the
+rest of this documentation explains them.
+
+If there are customizations that the Savvy API does not support, please
+file a bug::
+
+  https://bugs.launchpad.net/savilerow/+bugs
+
+And the team will do its best to respond.