git.sur5r.net Git - bacula/rescue/blob - rescue/linux/cdrom/yaird-0.0.5/doc/tools.xml

   1 <section id="tools">
   2   <title>Tool Chain</title>
   3   <para>
   4     This section discusses which tools are used in implementing
   5     <application>yaird</application> and why.
   6   </para>
   7
   8   <para>
   9     The application is built as a collection of perl modules.
  10     The use of a scripting language makes consistent error checking
  11     and building sane data structures a lot easier than shell
  12     scripting; using perl rather than python is mainly because in
  13     Debian perl has 'required' status while python is only 'standard'.
  14     The code follows some conventions:
  15   </para>
  16
  17   <para>
  18     <itemizedlist>
  19       <listitem>
  20         <para>
  21           Where there are multiple items of a kind, say fstab entries,
  22           the perl module implements a class for individual items.
  23           All classes share a common base class, <code>Obj</code>,
  24           that handles constructor argument validation and that offers
  25           a place to plug in debugging code.
  26         </para>
  27       </listitem>
  28
  29       <listitem>
  30         <para>
  31           Object attributes are used via accessor methods to catch
  32           typos in attribute names.
  33         </para>
  34       </listitem>
  35
  36       <listitem>
  37         <para>
  38           Objects have a <code>string</code> method, that returns
  39           a string version of the object.  Binary data is not
  40           guaranteed to be absent from the string version.
  41         </para>
  42       </listitem>
  43
  44       <listitem>
  45         <para>
  46           Where there are multiple items of a kind, say fstab entries,
  47           the collection is implemented as a module that is not a
  48           class.  There is a function <code>all</code> that returns a
  49           list of all known items, and functions <code>findByXxx</code>
  50           to retrieve an item where the Xxx attribute has a given
  51           value.  There is an <code>init</code> function that
  52           initializes the collection; this is called automatically
  53           upon first invocation of <code>all</code> or
  54           <code>findByXxx</code>.
  55           Collections may have convenience functions
  56           <code>findXxxByYyy</code>: return attribute Xxx, given a
  57           value for attribute Yyy.
  58         </para>
  59       </listitem>
  60
  61     </itemizedlist>
  62   </para>
  63
  64   <para>
  65     The generated initrd image needs a command interpreter;
  66     the choice of command interpreter is exclusively determined
  67     by the image generation template.
  68     At this point, both Debian and Fedora templates use the
  69     <application>dash</application> shell, for historical reasons only.
  70     Presumably <application>busybox</application> could be used to build a
  71     smaller image.  However, support for initramfs requires a complicated
  72     construction involving a combination of mount, chroot and chdir;
  73     to do that reliably, <application>nash</application> as used in Fedora
  74     seems a more attractive option.
  75   </para>
  76
  77   <para>
  78     Documentation is in docbook format, since it's widely supported,
  79     supports numerous output formats, has better separation between
  80     content and layout than texinfo, and provides better guarantees
  81     against malformed HTML than texinfo.
  82   </para>
  83
  84   <simplesect>
  85     <title>Autoconf</title>
  86     <para>
  87       GNU automake is used to build and install the application,
  88       where 'building' is perhaps too big a word adding the location
  89       of the underlying modules to the wrapper script.
  90       The reasons for using automake: it provides packagers with a
  91       well known mechanism for changing installation directories,
  92       and it makes it easy for developers to produce a cruft-free
  93       and reproducible tarball based on the tree extracted from
  94       version control.
  95     </para>
  96   </simplesect>
  97
  98   <simplesect>
  99     <title>C Library</title>
 100     <para>
 101       The standard C library under linux is glibc.  This is big:
 102       1.2Mb, where an alternative implementation, klibc, is only 28Kb.
 103       The reason klibc can be so much smaller than glibc is that a
 104       lot of features of glibc, like NIS support, are not relevant for
 105       applications that need to do basic stuff like loading an IDE driver.
 106     </para>
 107
 108     <para>
 109       There are other small libc implementations: in the embedded world,
 110       dietlibc and uClibc are popular.  However, klibc was specifically
 111       developed to support the initial image: it's intended to be included
 112       with the mainline kernel and allow moving a lot of startup magic out
 113       of the kernel into the initial image.  See
 114       <ulink url="http://marc.theaimsgroup.com/?m=101070502919547">
 115         <citetitle>
 116           LKML: [RFC] klibc requirements, round 2</citetitle></ulink>
 117       for requirements on klibc; the
 118       <ulink url="http://www.zytor.com/mailman/listinfo/klibc">
 119         <citetitle>mailing list</citetitle></ulink> is the most current
 120       source of information.
 121     </para>
 122
 123     <para>
 124       Recent versions of klibc (1.0 and later) include a wrapper around
 125       gcc, named klcc, that will compile a program with klibc.  This means
 126       <application>yaird</application> does not need to include klibc,
 127       but can easily be configured to use klibc rather than glibc.
 128       Of course this will only pay off if <emphasis>every</emphasis>
 129       executable on the initial image uses klibc.
 130     </para>
 131
 132     <para>
 133       <application>Yaird</application> does not have to be extended in
 134       order to support klibc, but it is necessary to avoid assumptions
 135       about which shared libraries are used.  This is discussed in
 136       <xref linkend="shlibs"/>.
 137     </para>
 138   </simplesect>
 139
 140   <simplesect>
 141     <title>Template Processing</title>
 142     <para>
 143       This section discusses the templates used to transform
 144       high-level actions to lines of script in the generated image.
 145       These templates are intended to cope with small differences
 146       between distributions: a shell that is named
 147       <application>dash</application> in Debian and
 148       <application>ash</application> in Fedora for example.
 149       By processing the output of <application>yaird</application>
 150       through a template, we can confine the tuning of
 151       <application>yaird</application> for a specific distribution
 152       to the template, without having to touch the core code.
 153     </para>
 154
 155     <para>
 156       One important function of a template library is to enforce
 157       a clear separation between progam logic and output formatting:
 158       there should be no way to put perl fragments inside a template.
 159       See <ulink url="http://www.stringtemplate.org/">StringTemplate</ulink>
 160       for a discussion of what is needed in a templating system, plus
 161       a Java implementation.
 162     </para>
 163
 164     <para>
 165       Lets consider a number of possible templating solutions:
 166       <itemizedlist>
 167
 168         <listitem>
 169           <para>
 170             <ulink url="http://www.template-toolkit.org/">
 171              Template Toolkit</ulink>:
 172             widely used, not in perl core distribution, does not
 173             prevent mixing of code and templates.
 174           </para>
 175         </listitem>
 176
 177         <listitem>
 178           <para>
 179             <ulink url="http://search.cpan.org/dist/Text-Template/lib/Text/Template.pm">
 180               Text::Template</ulink>:
 181             not in perl core distribution, does not
 182             prevent mixing of code and templates.
 183           </para>
 184         </listitem>
 185
 186         <listitem>
 187           <para>
 188             Some XSLT processor.  Not in core distribution,
 189             more suitable for file-to-file transformations
 190             than for expanding in-process data; overkill.
 191           </para>
 192         </listitem>
 193
 194         <listitem>
 195           <para>
 196             <ulink url="http://search.cpan.org/~samtregar/HTML-Template-2.7/Template.pm">
 197               HTML-Template</ulink>:
 198             not in perl core distribution,
 199             prevents mixing of code and templates,
 200             simple, no dependencies, dual GPL/Artistic license.
 201             Available in Debian as
 202             <application>libhtml-template-perl</application>,
 203             in Fedora 2 as perl-HTML-Template, dropped from Fedora 3,
 204             but available via
 205             <ulink url="http://download.fedora.redhat.com/pub/fedora/linux/extras/">
 206               Fedora Extras</ulink>.
 207           </para>
 208         </listitem>
 209
 210         <listitem>
 211           <para>
 212             A home grown templating system: a simple system such as the
 213             HTML-Template module is over 100Kb.  We can cut down on that
 214             by dropping functions we don't immediately need, but the effort
 215             to get a tested and documented implementation remains substantial.
 216           </para>
 217         </listitem>
 218
 219       </itemizedlist>
 220     </para>
 221
 222     <para>
 223       The HTML-Template approach is the best match for our
 224       requirements, so used in <application>yaird</application>.
 225     </para>
 226
 227   </simplesect>
 228
 229 </section>