Add sphinx documentation

1 files changed, 110 insertions, 0 deletions

diff --git a/doc/devel.rst b/doc/devel.rst
new file mode 100644
index 0000000..d6acf1f
--- /dev/null
+++ b/doc/devel.rst
@@ -0,0 +1,110 @@
+Developing live scripts and customisation hooks
+===============================================
+
+vmdebootstrap is available in git and in Debian. The live image
+processing requires several options which are only available in
+versions of vmdebootstrap newer than version 0.5-2 available in
+Debian Jessie. vmdebootstrap is able to run on Stretch, Jessie or
+Wheezy and able to build any suite supported by debootstrap (and
+and architecture supported by QEMU) on any of those versions of
+Debian. This leads to a large matrix of build options and hooks.
+
+Calls to vmdebootstrap are best scripted. See the README for notes
+on which options and settings are required to make a live image using
+vmdebootstrap.
+
+The 'common' library contains functions and parameters which need to
+be used in *all* images, including:
+
+cleanup
+export_env
+mount_proc
+disable_daemons
+prepare_apt_source
+remove_daemon_block
+replace_apt_source
+
+cleanup
+-------
+
+Ensure that proc is unmounted even if the customisation fails or else
+the image build itself will fail to unmount ${rootdir}.
+
+export_env
+----------
+
+Debconf needs to be set in noninteractive mode to prevent the image
+build waiting for keyboard intervention.
+
+mount_proc
+----------
+
+Many packages require /proc to be mounted inside the chroot during
+installation - cleanup must be specified as a trap if mount_proc is
+used: trap cleanup 0
+
+disable_daemons
+---------------
+
+Packages which include a daemon *must not* start those daemons inside
+the chroot as this will make the ${rootdir} appear busy and the unmount
+will fail. All scripts need to use remove_daemon_block after package
+installation is complete.
+
+prepare_apt_source
+------------------
+
+The final Debian mirror location is not useful during the build as there
+is a faster mirror available during the build. This function moves the
+specified mirror file aside and uses the nearby mirror. Always use with
+replace_apt_source.
+
+replace_apt_source
+------------------
+
+Requires prepare_apt_source to have been run first, then undoes the
+change to the apt sources and cleans up.
+
+TASK_PACKAGES
+-------------
+
+Some task packages are useful to all images, these are specified here
+and should be included in the set of packages to be installed using
+all customisation scripts.
+
+EXTRA_PACKAGES
+--------------
+
+Packages which are not part of an existing task but which are useful for
+all images and should be included in the set of packages to be installed
+using all customisation scripts.
+
+Testing
+-------
+
+Testing - unsquashfs <filename> creates a squashfs-root/ directory
+containing the original image which QEMU can now use:
+$ unsquashfs jessie.img.squash
+$ qemu-system-x86_64 -machine accel=kvm:tcg -m 4096 -smp 2 -drive file=squashfs-root/jessie.img,format=raw
+
+This needs to be done on a local system which has a usable display,
+not on pettersson itself.
+
+New architectures
+-----------------
+
+The precursor to new architecture support is vmdebootstrap support. A
+default vmdebootstrap (with no customisation hook) will need to work
+and any changes to the settings (e.g. --no-kernel --package linux-myarch-flavour)
+There is default support for some architectures in vmdebootstrap
+(e.g. armhf architectures select the armmp kernel), such support depends
+on how many users would use the same kernel compared to the number of
+possible kernel flavours for that architecture.
+
+For a Debian LIVE image, *all* packages must exist in Debian.
+
+The package list also needs a review - some packages will simply not
+exist for the specified architecture. Some architecture-specific packages
+need to be added, so each architecture has a particular customisation
+hook script. Package names frequently change between releases, so the
+package selection needs to be suite specific as well.