[Fedora-livecd-list] Refactoring livecd-creator and providing an API

[Jeremy Katz]

It's time to get back to something that's been discussed on and off for
a while now and really do it.  And that's to refactor out the core of
livecd-creator so that it can be used for generating other types of
images as well as then providing an API to be used by people wanting to
build various types of interfaces on top of the tools.

After sitting down and poking a little, I've got something that I'm at
least starting to be happy with and figure it's about time to put it up
for others to look at and poke at.  Right now, the git tree is on
fedorapeople rather than in the main repo.  You can get it with
  git clone http://katzj.fedoraproject.org/git/livecd-tools.git

I've written up a short overview of the API and included it in the repo
and attached it to this message as well.  I've tried to keep the amount
that we expose pretty minimal so that we can continue to have a fair bit
of freedom in changing out the backend bits, especially the ones related
to writing out configuration[1] info.

Comments and suggestions appreciated, especially from those building on
top of livecd-tools or wanting to build other image builders.  I'm going
to likely go ahead and get this merged within the next week or so as
long as it's not entirely crazy.  Also, it's pending on splitting up the
current __init__ into separate modules to allow for cleaner namespacing

Jeremy

[1] In the future, this is something that we want to be able to share
with anaconda as we're currently doing a lot of duplication of bugfixes
and having to deal with slight variations in behavior between the two.
Which sucks.
-------------- next part --------------
In addition to livecd-creator itself, the livecd-creator package
provides a python API for building your own, other types of images.
This API could also be used to build on top of the live image
functionality.

== Image Creation Frontends ==

livecd-creator is one frontend for creating images.  But really, it's
straight-forward to build your own which deals with your own specific
needs.  To do so, you'll want to do the following:

* Create a pykickstart handler object.  All of the image creators are
driven by data stored in pykickstart handlers.
* Then, create an image
    image = ImageCreator(ks, fslabel)
  where ks is your pykickstart object and fslabel is the label/name you
  want for the image.
* With the image, you can either do everything in one-shot with
    image.create()
  or call the steps of image.create() itself.  The latter lets you add
  an interactive shell step if you want as well as a few other
  options.  The order, though, is
    image.mountImage()
    image.installPackages()
    image.configureImage()
    image.unmountImage()
    image.package()

  Other available methods are
    * image.launchShell(): This launches a root shell within the
      install root
    * image.teardown(): Tear down the image.  Note that this also
      occurs when the image object is deleted
    * image.getKernelVersions(): Returns a dict of kernels installed
      mapping from kernel type -> version
 

== Image Creator Backends ==

The basic idea is that there are (presently) 3 main classes used to
implement different types of images.  No matter which you use, the
interface should be largely the same.  This means that, eg,
livecd-creator _could_ generate other types of outputs just by
switching from the LiveImageCreator to another ImageCreator object.

* ImageCreatorBase: This is the guts of what most image creators will
  need to use.  It provides all of the bits to handle a kickstart
  config, install packages into an install root, etc.  It leaves
  basically four methods which must be implemented by more specific creators:
   i) _mountInstallRoot(self): This method is where your filesystems
   should get mounted.  The root of your filesystem tree should be
   located at self._instroot
   ii) _unmountInstallRoot(self): This method is called to undo
   _mountInstallRoot() basically.
   iii) configBoot(self): Set up anything needed for your image to
   boot.  This could involve creating an initramfs, writing a
   bootloader configuration, etc.  The filesystem is still mounted at
   self._instroot at this point.  Note that this could be a no-op.
   iv) package(self): Do whatever is needed to make your image
   "consumable".  eg, for live CDs, this is where we generate the iso
   images.  Note that this could be a no-op.

  Other methods which can be overriden if you have a specific need.
  But note that if you do, you should be sure to call the
  ImageCreatorBase method as well or the results can be undefined
   * runPost(): Runs kickstart post scripts.  If you have other
     configuration bits, this is the place for them.

  Overriding other methods is not supported or guaranteed to continue
  to give consistent results over time.

* LoopImageCreator: This generates ext3 images in a loopback file
  which could then later be booted in a virtual machine environment.
  NOTE: this does nothing to set up booting

* LiveImageCreator: This builds on top of the LoopImageCreator to
  build live images which use dm-snapshot, etc.  This is what is used
  by livecd-creator.