API

   1 In addition to livecd-creator itself, the livecd-creator package
   2 provides a python API for building your own, other types of images.
   3 This API could also be used to build on top of the live image
   4 functionality.
   5
   6 == Image Creation Frontends ==
   7
   8 livecd-creator and image-creator are both frontends for creating
   9 images.  But really, it's straight-forward to build your own which
  10 deals with your own specific needs.  To do so, you'll want to do
  11 the following:
  12
  13 * Create a pykickstart handler object.  All of the image creators are
  14 driven by data stored in pykickstart handlers.
  15 * Then, instantiate a creator
  16     creator = ImageCreator(ks, name)
  17   where ks is your pykickstart object and name is the label/name you
  18   want for the image.
  19 * With the image, you can either do everything in one-shot with
  20     creator.create()
  21   or call the steps of creator.create() itself.  The latter lets you add
  22   an interactive shell step if you want as well as a few other
  23   options.  The order, though, is
  24     creator.mount()
  25     creator.install()
  26     creator.configure()
  27     creator.unmount()
  28     creator.package()
  29
  30   Other available methods are
  31     * creator.launch_shell(): This launches a root shell within the
  32       install root
  33     * creator.cleanup(): Tear down the image.  Note that this also
  34       occurs when the image object is deleted
  35
  36
  37 == Image Creator Backends ==
  38
  39 The basic idea is that there are (presently) 3 main classes used to
  40 implement different types of images.  No matter which you use, the
  41 interface should be largely the same.  This means that, eg,
  42 livecd-creator _could_ generate other types of outputs just by
  43 switching from the LiveImageCreator to another ImageCreator object.
  44
  45 * ImageCreator: This is the guts of what most image creators will
  46   need to use.  It provides all of the bits to handle a kickstart
  47   config, install packages into an install root, etc.  It leaves
  48   a number of hook methods which maybe be implemented by more specific
  49   creators:
  50    i) _mount_instroot(self): This method is where your filesystems
  51    should get mounted.  The root of your filesystem tree should be
  52    located at self._instroot
  53    ii) _unmount_instroot(self): This method is called to undo
  54    _mount_instroot() basically.
  55    iii) _create_bootconfig(self): Set up anything needed for your
  56    image to boot.  This could involve creating an initramfs, writing a
  57    bootloader configuration, etc.  The filesystem is still mounted at
  58    self._instroot at this point.  Note that this could be a no-op.
  59    iv) _stage_final_image(self): Do whatever is needed to make your
  60    image "consumable" and copy it to self._outdir.  eg, for live CDs,
  61    this is where we generate the iso images.  Note that this could be
  62    a no-op.
  63
  64   Other hooks are available to subclasses, as well as a number of
  65   helper methods which can be used in implementing the hooks. See
  66   the inline docstrings for more details.
  67
  68   Overriding other methods is not supported or guaranteed to continue
  69   to give consistent results over time.
  70
  71 * LoopImageCreator: This generates ext3 images in a loopback file
  72   which could then later be booted in a virtual machine environment.
  73   NOTE: this does nothing to set up booting
  74
  75 * LiveImageCreator: This builds on top of the LoopImageCreator to
  76   build live images which use dm-snapshot, etc.  This is what is used
  77   by livecd-creator.
  78