<epigraph>
  <attribution>anonymous</attribution>
  <simpara>
    Once it hits the fan, the only rational choice is to sweep it up,
    package it, and sell it as fertilizer.
  </simpara>
</epigraph>

<simpara
  >This document tries to cover multiple platforms
  through conditional compilation. There is a
  <filename>configure.pl</filename> that determines the host type
  and sets up a <filename>config.sh</filename> containing environment
  variable definitions.
  There also are equivalent
  <filename>config.csh</filename>, <filename>config.h</filename>,
  <filename>config.mak</filename>, <filename>config.sed</filename>,
  and <filename>config.xml</filename>.
  The <filename>Makefile</filename> then uses individual sub-directories
  for each platform. The name of these directories (and some other
  platform specific values) is retrieved through environment
  variables. The directory structure is not without meaning.
</simpara>
<para
  ><itemizedlist>
    <listitem><simpara>
      <filename>src/</filename> is for source code, i.e. text files
      written and maintained by humans.
    </simpara></listitem><listitem><simpara>
      <filename>&config.PRE;/</filename> is directory
      <filename>src/</filename> pre-processed with
      <filename>config.sed</filename>.
      In <filename>pre/</filename> all program names are absolute.
      Magic numbers and platform specific constants are verbatim.
    </simpara></listitem><listitem><simpara>
      <filename>&config.TMP;/</filename> is the only place to hold
      binaries, i.e. executables and <filename>.o</filename> files.
    </simpara></listitem><listitem><simpara>
      <filename>&config.OUT;/</filename> is for the output of
      executables, hex dumps, disassembly listings, text processing.
    </simpara></listitem>
  </itemizedlist>
</para>

<sect2 id="variables.prefixed.with.tevwh"
  xreflabel="Variables prefixed with TEVWH_">
  <title>Variables prefixed with <literal>TEVWH_</literal></title>

  <simpara
    >The files in <filename>src/</filename> are obfuscated with obscene
    amounts of variable references like <literal>${TEVWH_ELF_BASE}</literal>
    or even <literal>${TEVWH_PATH_LS}</literal>.
    I admit that using variables instead of plain program names makes
    shell scripts harder to read. But this is necessary to maintain a
    minimum level of reproducibility on SunOS.
    Anyway, directory <filename>pre/</filename> makes that
    <literal>&config.ELF.BASE;</literal> and
    <literal>&config.PATH.LS;</literal>, so you will probably never
    encounter this syntax nightmare. 
    An almost complete list of used variables is given below.
  </simpara>

  <table frame="none" pgwide="1">
    <title>Variables prefixed with <literal>TEVWH_</literal></title>
    &xml.variables;
  </table>

  <simpara
    >Note that hexadecimal shell variables actually miss the leading
    <literal>0x</literal> to simplify calculations with
    <application>bc</application>.
    These values are also available to C code through corresponding
    <literal>#define</literal> statements after
    <literal>#include &lt;config.h&gt;</literal>.
    Values are not quoted, but hexadecimal values are correctly
    prefixed by <literal>0x</literal>.
  </simpara>

</sect2>
<sect2 id="variables.prefixed.with.tevwh.path"
  xreflabel="Variables prefixed with TEVWH_PATH">
  <title>Variables prefixed with <literal>TEVWH_PATH_</literal></title>

  <table frame="none" pgwide="1">
    <title>Variables prefixed with <literal>TEVWH_PATH_</literal></title>
    &xml.path;
  </table>

</sect2>
<sect2 id="the.name.of.the.x" xreflabel="The name of the X">
  <title>The name of the X</title>
  
  <formalpara>
    <title>Command: src/packages/uname.sh</title>
    <para>
      <programlisting><inlinemediaobject><imageobject><imagedata
	format="linespecific" 
	fileref="../../src/packages/uname.sh"
      /></imageobject></inlinemediaobject></programlisting>
    </para>
  </formalpara>
  <formalpara>
    <title>Output: &config.OUT;/packages/uname</title>
    <para>
      <programlisting><inlinemediaobject><imageobject><imagedata
	format="linespecific" 
	fileref="../../&config.OUT;/packages/uname"
      /></imageobject></inlinemediaobject></programlisting>
    </para>
  </formalpara>

  &xml.packages.distid;

</sect2>
<sect2 id="the.owner.of.files"
  xreflabel="The owner of files">
  <title>The owner of files</title>

  <simpara
    >One of the lesser known features of package management is
    self-reflection. How do we determine the package owning a file
    if we have the canonical path name?
  </simpara>

  &xml.packages.finding.owner;

</sect2>

&xml.packages.nopkg;

<sect2 id="source.of.man.pages"
  xreflabel="The source of man-pages">
  <title>The source of man-pages</title>

  <simpara
    >Option <option>-a</option> of <application>man</application>
    returns all matching entries, not just the lowest section.
    This behavior is identical between platforms.
  </simpara>

  <formalpara>
    <title>Command: &config.PRE;/packages/man-all/&config.UNAME;.sh</title>
    <para>
      <programlisting><inlinemediaobject><imageobject><imagedata
	format="linespecific" 
	fileref="../../&config.PRE;/packages/man-all/&config.UNAME;.sh"
      /></imageobject></inlinemediaobject></programlisting>
    </para>
  </formalpara>
  <formalpara>
    <title>Output: &config.OUT;/packages/man-all</title>
    <para>
      <programlisting><inlinemediaobject><imageobject><imagedata
	format="linespecific" 
	fileref="../../&config.OUT;/packages/man-all"
      /></imageobject></inlinemediaobject></programlisting>
    </para>
  </formalpara>

  <simpara
    >Requesting a specific section requires option
    <option>-s <replaceable>section</replaceable></option> on SunOS,
    while Linux and FreeBSD prefer a plain
    <option><replaceable>section</replaceable></option>.
  </simpara>

  <formalpara>
    <title>Command: &config.PRE;/packages/man-section/&config.UNAME;.sh</title>
    <para>
      <programlisting><inlinemediaobject><imageobject><imagedata
	format="linespecific" 
	fileref="../../&config.PRE;/packages/man-section/&config.UNAME;.sh"
      /></imageobject></inlinemediaobject></programlisting>
    </para>
  </formalpara>
  <formalpara>
    <title>Output: &config.OUT;/packages/man-section</title>
    <para>
      <programlisting><inlinemediaobject><imageobject><imagedata
	format="linespecific" 
	fileref="../../&config.OUT;/packages/man-section"
      /></imageobject></inlinemediaobject></programlisting>
    </para>
  </formalpara>

</sect2>
<sect2 id="verifying.installed.packages"
  xreflabel="Verifying installed packages">
  <title>Verifying installed packages</title>

  <simpara
    >This chapter is not about checking the integrity of package files.
    See &yref.ids; for a general introduction.
  </simpara>

  &xml.packages.verify;

</sect2>
