~ubuntu-installer/ubiquity/trunk

Ubiquity

========

This is a graphical installer for Ubuntu, written largely in Python, using

d-i as a backend for many of its functions. The authors are indebted to the

efforts of the Guadalinex project in developing the original

"ubuntu-express" code used as a basis for this project.

Background

----------

Around 2000, the debian-installer (later just "d-i") project started to

replace the old Debian "boot-floppies" installer. The goals of this project

included long-term maintainability, modularity, and code reuse. After a

hiatus during the Debian 3.0 release, this project matured into a usable

installer in 2004 in time for, among others, the releases of Debian 3.1 and

Ubuntu 4.10. From Ubuntu 4.10 to Ubuntu 5.10, d-i was used as the primary

installation program.

d-i continues to provide flexibility and (for a certain significant class of

users) ease of use that a simplified graphical installer will always be

hard-pushed to provide. It is therefore important to continue to support it

in Ubuntu. From a maintainability point of view, it follows that it is

important for any graphical installer supported by Ubuntu to share

substantial amounts of code with d-i, particularly where the backend logic

is intrinsically difficult and has accumulated large quantities of expertise

and bug fixes. Accordingly, Ubiquity is designed to use logic from d-i where

possible, and tries to confine itself to being a high-quality frontend.

(Of course, there remain some areas where d-i does not provide suitable

logic, or where its logic has not proven amenable to direct use within

Ubiquity, so there is still some backend-style logic and code duplication

in Ubiquity. Eventually, as much of this as possible should go away.)

UI Design

---------

The primary focus of Ubiquity's UI is ease of use for new users.

Accordingly, it does not try to provide all possible options, deferring

advanced installation scenarios to d-i so that it does not have to be all

things to all people. See http://wiki.ubuntu.com/UbuntuExpress for the

original details of its user interface design.

Debconf Integration

-------------------

The most challenging part of Ubiquity to understand is undoubtedly its

integration with d-i. Before getting to grips with this, I assume that the

reader has a basic developer-level grasp of the "debconf" configuration

system. Reading the debconf-devel(7) man page is a good idea.

d-i uses debconf for all user interaction. The extant graphical debconf

frontends are functional, but crude from a human interface design

perspective; although this could be improved, the problem is to some extent

intrinsic because they must generate a user interface based on the questions

asked by the confmodule. It is possible to do much better using custom user

interface code. However, at present debconf has no support for doing this

directly (although cdebconf does).

To deal with this, Ubiquity uses the noninteractive debconf frontend, and

instead uses a layer called the "debconffilter". This sits between d-i code

and the debconf frontend, intercepting the debconf protocol, and transforms

relevant debconf protocol messages into events which can be handled in much

the same way as UI events from widget libraries like GTK+ or Qt. While this

requires insider knowledge of the questions which may be asked by each piece

of d-i code, which must often be updated as d-i evolves, it seems to be the

most practical approach at present.

Each piece of d-i code used in Ubiquity is accompanied by a "component",

written in Python, which defines the backend code to be called and any

necessary event handlers. To allow for multiple frontend implementations, it

typically calls methods in the frontend when UI operations are needed.

It is important to remember that each call to component event handlers is

blocking (though non-reentrant). If UI interaction is required in order to

provide an answer to debconf, this must be handled by calling into suitable

frontend functions from the component to wait for the user. The component is

responsible for maintaining its own state machine if necessary.

Partitioning

------------

All partitioning is handled by d-i code (partman), with a presentation layer

on top. The presentation layer navigates partman's menus under the hood to

perform advanced partitioning. See

http://wiki.ubuntu.com/Ubiquity/AdvancedPartitionerRewrite for details.

A graphical disk view has yet to be written for the GTK frontend's advanced

partitioner.

Installation

------------

The actual installation takes place by copying the read-only part of the

live filesystem. The writable part of the live filesystem (i.e. the running

live session) is intentionally not copied, to ensure maximum reproducibility

of the installed system. Thus, any customisations applied by the live boot

process must be re-applied after the read-only filesystem is copied. The

live boot process is responsible for installing hooks in

/usr/lib/ubiquity/target-config/ to take care of this.

After copying the live filesystem, certain unnecessary packages (such as

Ubiquity itself) will be removed. The set of packages to be removed is

computed by taking those packages present in

/cdrom/casper/filesystem.manifest-remove (or, in older versions of Ubuntu,

those packages present in /cdrom/casper/filesystem.manifest but not present

in /cdrom/casper/filesystem.manifest-desktop), and removing any packages

explicitly requested for installation by installer code. Language packs for

languages which are not to be supported on the installed system will also be

removed.

Logs of the installation will be saved in /var/log/syslog (for messages

emitted by Ubiquity itself and messages emitted by d-i code), and

/var/log/partman (for a trace of the operation of the automatic

partitioner). /var/log/syslog and /var/log/partman are saved in

/var/log/installer/ on the installed system.

Customisation

-------------

Where d-i code is used, it is generally possible to preseed it to change

default behaviour. See the installation guide for details. By default,

preseeding is confined to setting default values for questions, and Ubiquity

will not skip over preseeded steps (this is to allow sensible interpretation

of going backward and forward in the UI); if the --automatic option is used,

preseeded steps will be skipped.

The read-only live filesystem should generally be mounted on /rofs.

Alternatively, an image may be present as /cdrom/casper/filesystem.cloop,

/cdrom/casper/filesystem.squashfs, or (for Guadalinex/Metadistros)

/cdrom/META/META.squashfs. Ubuntu currently uses

/cdrom/casper/filesystem.squashfs. You can preseed

ubiquity/install/filesystem-images with a space-separated list of image

paths to override this; if you provide more than one image, then they will

be overlaid using unionfs.

/cdrom/casper/filesystem.manifest should be a list of packages in the full

live filesystem; the format is that produced by running "dpkg-query -W".

/cdrom/casper/filesystem.manifest-remove should be a list of packages to

remove from the target system after copying the live filesystem. This allows

Ubiquity to ensure that, for example, Ubiquity itself doesn't end up on the

target system.

Language packs for the selected language are installed by default, using the

Ubuntu naming scheme of language-pack-$LL and language-support-$LL. If you

want to get rid of these (for example because their dependencies are

inconvenient), then you can preseed pkgsel/language-packs to the empty

string.

If /cdrom/.disk/release_notes_url is present, a link to the release notes

will be displayed on the language page. Instances of the string ${LANG} in

that URL will be replaced with the locale, with any encoding removed (e.g.

en, de, pt_BR, zh_CN).

If you're installing from a medium other than a CD or DVD (e.g. over NFS),

then the path of least resistance is to arrange that something that looks

like a CD is available on /cdrom anyway. NFS-mounting an entire CD image is

one approach that has worked with relatively little effort, but you could

also set up the files listed above in some other way.

Frequently Asked Questions

--------------------------

Q. Can I backport the version of Ubiquity from the current Ubuntu

   development release to the previous stable release?

A. Not without quite a bit of work. At present, Ubiquity is still a complex

   piece of software with several bleeding-edge dependencies, and at the

   moment I have no compunctions about making it depend on new packages or

   newer versions of existing packages in order to get the job done

   properly. In future, things may settle down such that there can be more

   compatibility guarantees, particularly if Ubiquity is adopted by other

   Debian-based distributions.

   At the moment, I can think of the following specific issues with

   backporting Ubiquity from Ubuntu 6.10 to Ubuntu 6.06:

     * Ubiquity now uses the new Python policy, which involves a number of

       packaging changes and even a couple of code changes that are

       incompatible with Ubuntu 6.06. These would need to be reverted.

     * Ubiquity now uses console-setup as the backend for the keyboard

       screen rather than kbd-chooser. console-setup will not work on Ubuntu

       6.06, so the kbd-chooser code would need to be resurrected.

     * Ubiquity's GTK frontend now relies on new features in gparted in

       order to fix some user interface bugs.

     * Ubiquity now integrates with the apport crash reporting facility in

       Ubuntu 6.10, which is not available in Ubuntu 6.06. (This would just

       be a matter of removing dependencies; it's optional as far as the

       code is concerned.)

     * Ubiquity's debconf template translations now rely on new features in

       po-debconf 1.0, which was not available in Ubuntu 6.06.

   While I'm aware that there were a number of serious issues with the

   version of Ubiquity that shipped with Ubuntu 6.06 (many of which were

   corrected in Ubuntu 6.06.1), I feel that the right answer to these is to

   backport selected fixes to that branch of Ubiquity rather than trying to

   backport the whole package.

   Similarly, there are at least the following issues with backporting

   Ubiquity from Ubuntu 7.04 to Ubuntu 6.10:

     * Ubiquity depends on a version of console-setup at least as new as the

       one in its own source tree, so the two packages would need to be

       backported together. The new version of console-setup in turn relies

       on a newer version of xkb-data (although probably not inextricably).

     * Ubiquity's GTK frontend now uses gtk.LinkButton, which isn't

       available in the versions of GTK+/PyGTK in Ubuntu 6.10. Similarly,

       you need a more recent version of glade-3 than is available in Ubuntu

       6.10 to edit the user interface definition for the GTK frontend.

     * Regenerating Ubiquity's autotools files (configure et al) requires

       Automake 1.10, not available in Ubuntu 6.10.

     * Ubiquity's apport crash handler now requires a new Python API

       introduced in apport 0.33.

Feel free to ask us (ubuntu-installer@lists.ubuntu.com) if you have any

questions regarding Ubiquity's workings.