The Mythbuntu project is split up into many components that are intertwined with Ubuntu components. Eventually it will be broken up enough that each component can be modified without requiring many modifications to Ubuntu or common core components.

This document explains how the project is organized. It was last updated as of Mythbuntu 10.04, so some content may change from time to time.

Getting Started

Before starting, you should familiarize yourself with the following subsections:

Live CD

The LiveCD contains the following (critical) items:
  • A "casper" directory containing a live squashfs, initrd, and list of manifests.
  • A "pool" and "dists" directory that contain a pool of installable archives.
  • A ".disk" directory containing a UUID that matches the initrd in casper/
Other items are contained on the LiveCD, but not important to the critical functionality.

This squashfs is generated by the livecd-rootfs project. It's code can be viewed at

bzr get lp:livecd-rootfs

The build keys off of the two tasks 'mythbuntu-desktop' and 'mythbuntu-live'. These will be discussed further in the "Meta Packages & Seeds" section.

The LiveCD menu structure, pool and graphics are both generated from the Ubuntu debian-cd 

bzr branch.bzr get lp:~ubuntu-cdimage/debian-cd/ubuntu
  • The graphics are located at data/RELEASE/mythbuntu.png and data/RELEASE/mythbuntu.pcx
  • The default preseed file is located at data/RELEASE/preseed/mythbuntu/mythbuntu.seed
The pool is populated using the seeds described in "Meta Packages & Seeds" later in this document.

Currently, the Squashfs & Live CD are built on a daily cron job and published at 1:06AM CST at http://cdimages.ubuntu.com/mythbuntu/daily-live

If there are problems with the squashfs build, the details can be found at: http://people.canonical.com/~ubuntu-archive/livefs-build-logs/lucid/mythbuntu/

If there are problems with the LiveCD build, the details can be found at: http://people.canonical.com/~ubuntu-archive/cd-build-logs/mythbuntu/lucid/

Functionality

The LiveCD works like a live system thanks to a kernel module called "aufs". It creates a union filesystem between a read-only squashfs and a temporary filesystem in the system's RAM. The size of this tmpfs is determined by the amount of memory in the computer.

You will notice the behavior of the live environment is customized to be a little bit different than that of a fully installed system. This is caused by two packages.

The first package is casper. Casper is a collection of scripts that get ran early in the boot from initrd that will make customizations that are only sitting in the tmpfs. You can fetch casper from the Ubuntu bzr branch:

bzr get lp:ubuntu/casper

Generally things like creating a live cd user, and preventing services from starting happen here. Mythbuntu makes no modifications to casper.

The second package is mythbuntu-live-autostart. It provides the following:
  • A Mythbuntu specific collection of caspers script to stop Apache, MySQL, and Mythbackend from launching as well as change some default behaviors
  • The Ubiquity slideshow for Mythbuntu
  • An application for configuration of the frontend connectivity information prior to launch on a LiveCD
  • The Mythbuntu plugin set for Ubiquity. This provides any of the pages and backend functionality that's not present in the standard GTK frontend.
You can obtain mythbuntu-live-autostart from it's bzr branch:

bzr get lp:~mythbuntu/mythbuntu/mythbuntu-live-autostart

Meta Packages & Seeds

A seed is a text file used to declare what packages will be included for a given task or metapackage. A task is used for the initial installation during a squashfs build or from a d-i installation.

Information about how seeds work can be found on the Ubuntu wiki:
For Mythbuntu, the seeds can be found at:

bzr get lp:~mythbuntu/ubuntu-seeds/mythbuntu.precise

Here's the basics:
  • Syntax:
    • Starting with " *" means that something is a dependency
    • Starting with " * (" and ending with ")" means that it's a recommends
    • Starting with "Task" means that this is a task related key
    • All else is treated as comments
  • desktop: This seed is used for generating the list of things included in the "mythbuntu-desktop" metapackage and task. It has a dependency on all stuff in the Ubuntu platform 'minimal' seed.
  • live: This seed is used for generating the list of things included in the "mythbuntu-live" metapackage ans task. It has a dependency on all stuff in the "desktop" seed.
  • ship-live: This seed is used by debian-cd for populating the pool with packages to be placed directly on the media.
A metapackage is used to transition users to new packages that should be included in the install. Whenever a change is made to the 'desktop' or 'live' seeds, the metapackages should be regenerated. The metapackage bzr branch can be found at:

bzr get lp:~mythbuntu/mythbuntu/mythbuntu-meta

Making changes to this branch will require that you have a recent version of "germinate" installed as well as the package "devscripts".

The update mechanism can be ran by running "./update" from the root of the bzr branch. This will read the data in ./update.cfg and use it to determine where to fetch the seeds from as well as archive information. Make sure that you have set "dist" properly in update.cfg before running this. The end result cause debian/changelog to be incremented with the new changes and each of the lists to call out the appropriate packages.

If there are problems with extra packages being included, that shouldn't be, view these URLs to figure out where the dependency problem is generated:

Default Settings

The Mythbuntu default settings package provides the xsession and all the default settings involved. It can be fetched from:

bzr get lp:~mythbuntu/mythbuntu/mythbuntu-default-settings
  • All of the actions that are done with the login session are stored at:
usr/share/mythbuntu/session.sh
  • The gconf override defaults are stored at:
usr/share/gconf/defaults/10_mythbuntu-default-settings
  • The default XFCE settings are stored at:
etc/xdg/mythbuntu
  • The default theme inherits from Humanity, so the icon overrides are stored at:
usr/share/icons/Mythbuntu

LightDM Theme

The Mythbuntu lightdm theme package controls what applications are launched at LightDM to set up the correct view.

bzr get lp:~mythbuntu/mythbuntu/mythbuntu-lightdm-theme

USplash Theme

The Mythbuntu usplash theme is the theme that is flashed/pulsed before GDM comes up. It can be fetched from:

bzr get lp:~mythbuntu/mythbuntu/mythbuntu-artwork-usplash

Log Grabber

The Mythbuntu log grabber is a tool shipped on systems to assist with helping to debug problems on the system. It can be fetched from:

bzr get lp:~mythbuntu/mythbuntu/mythbuntu-log-grabber

Control Centre

Mythbuntu Control Centre (MCC) provides a framework for allowing plugins to be loaded from /usr/share/mythbuntu/plugins that allow different aspects of the system to be configured. It can be fetched from:

bzr get lp:~mythbuntu/mythbuntu/mythbuntu-control-centre

The control centre does not provide any plugins by default. An example plugin is however included in the bzr tree that can be used as a reference to develop a plugin. Because of this extensible model, plugins can be added / provided by external packages. MCC allows hooks to run things as a user, as root, or to add/remove a package.

Common

Mythbuntu common provides pieces of code that are used in several Mythbuntu projects, such as MCC, Ubiquity and Mythbuntu Live Autostart. Also, all MCC base plugins are included. It can be fetched from:

bzr get lp:~mythbuntu/mythbuntu/mythbuntu-common

Common modules used by many parts are included in the mythbuntu_common/ directory. Plugins for MCC are included in the plugins/ directory.

Remote Control

Remote control support is mostly provided directly by the LIRC package, but several other packages exist to help support it. The LIRC bzr tree can be fetched from:

bzr get lp:~mythbuntu/lirc/ubuntu

All of the kernel modules are also included in the ubuntu/ subdirectory of the kernel project. Whenever a new version of LIRC is updated, a patch needs to be submitted to the kernel-team@lists.ubuntu.com mailing list to include the new version of LIRC. This tree can be viewed at: http://kernel.ubuntu.com/git?p=ubuntu/ubuntu-lucid.git;a=tree;f=ubuntu/lirc

LIRC requires that all buttons be mapped to functions for individual applications. To help assist with this, a dictionary project, mythbuntu-lirc-generator was created. It can be fetched from:

bzr get lp:~mythbuntu/mythbuntu/mythbuntu-lirc-generator

Lastly, MLG and LIRC are glued together w/ GUI support via mythbuntu-common. Mythbuntu common can be fetched from:

bzr get lp:~mythbuntu/mythbuntu/mythbuntu-common

Both the mythbuntu_common/lirc.py and plugins/python/remote.py are used for this.

MythTV

The MythTV package is built exclusively from git. It includes mythplugins and myththemes all in the same package. To build it, you want to first checkout the packaging from git. Depending on what you are working on, you may want the 'fixes/0.$REVISION' or the '-master' branch. The fixes branch is considered stable and regularly updated upstream. Once you clone out, use git to switch branches.

To clone:

git clone git://github.com/MythTV/packaging.git

To check out the -fixes packaging:

git branch fixes/0.25

After you've checked out the packaging, switch into the deb directory of the checked out directory to build a source or binary package.

cd deb 
./build-dsc.sh /tmp
or
./build-deb.sd /tmp

The version number that will be checked out is controlled by the latest version defined in debian/changelog .

Automatic Daily Builds

A service is provided to users to automatically build new checkouts of -fixes and -master branches of upstream mythtv, mythplugins, and myththemes whenever changes are made. To provide this service, a collection of shell scripts control the logic for the builds.

Today, these shell scripts are actually wrappers around an upstream packaging shell script that is kept at https://github.com/MythTV/packaging.

This collection can be fetched from the following bzr branch:

bzr get lp:~mythbuntu/mythbuntu/mythbuntu-weekly-build

For mostly historical reasons the branch is titled 'mythbuntu-weekly-build'. It actually is ran daily.

Building

A continuously updated snapshot of git and bzr is maintained on a build machine. Each day before the set of builds it will pull packaging updates from bzr and source updates from git. This means that any changes committed to the branch automatically propagate to this machine. Within this branch there is a top level script:
build_mythtv.sh

This script sources variables from variables_common.sh to control what to build, version numbers to assign and much more. The script is fairly well documented. After the source package is built, it's pushed to the PPA build system for the mythbuntu team at http://launchpad.net/~mythbuntu.

If you would like to perform a set of local builds, the scripts can be easily adapted to include patches in either the git source or the bzr packaging. When git is pulled it will always rebase the patches on top of HEAD. If you make modifications to the bzr packaging, the bzr pull should automatically rebase as well provided there are no conflicts.