source: introduction/important/unpacking.xml@ b92d4b3

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;
]>

<sect1 id="intro-important-unpacking">
  <?dbhtml filename="unpacking.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Notes on Building Software</title>

  <para>Those people who have built an LFS system will be aware 
  of the general principles of downloading and unpacking software.  We will
  however repeat some of that information here for those new to building
  their own software.</para>

  <para>Each set of installation instructions contains a URL from which you 
  can download the package.  We do however keep a selection of patches 
  available via http.  These are referenced as needed in the installation 
  instructions.</para>

  <para>While you can keep the source files anywhere you like, we
  assume that you have unpacked them and unzipped any required patches
  into <filename>/usr/src</filename>.</para>

  <para>We can not emphasize strongly enough that you should start from a
  <emphasis>clean source tree</emphasis> each time. This means that if
  you have had an error, it's usually best to delete the source tree and
  re-unpack it <emphasis>before</emphasis> trying again. This obviously
  doesn't apply if you're an advanced user used to hacking Makefiles and C
  code, but if in doubt, start from a clean tree.</para>

  <sect2>
    <title>Unpacking the Software</title>

    <para>If a file is tar'ed and compressed, it is unpacked by running one of
    the following commands:</para>

<screen><command>tar -xvf filename.tar.gz
tar -xvf filename.tgz
tar -xvf filename.tar.Z
tar -xvf filename.tar.bz2</command></screen>

    <para>You can also use a slightly different method:</para>

<screen><command>bzcat filename.tar.bz2 | tar -xv</command></screen>

    <para>Finally, you sometimes need to be able to unpack patches which are
    generally not tar'ed.  The best way to do this is to copy the patch file to
    <filename>/usr/src</filename> and then to run one of the following commands
    depending on whether the file is <filename>.gz</filename> or 
    <filename>.bz2</filename>:</para>

<screen><command>gunzip -v patchname.gz
bunzip2 -v patchname.bz2</command></screen>

  </sect2>

  <sect2>
    <title>Verifying File Integrity Using 'md5sum'</title>

    <para>Generally, to verify that the downloaded file is genuine and complete,
    most package maintainers also distribute md5sums of the files.
    To verify the md5sum of the downloaded files, download both the file and the
    corresponding md5sum file to the same directory (preferably from different
    on-line locations), and (assuming file.md5sum is the md5sum file downloaded)
    run the following command:</para>

<screen><command>md5sum -c file.md5sum</command></screen>

    <para>If there are any errors, they will be reported.</para>

  </sect2>

  <sect2>
    <title>Creating Log Files During Installation</title>

    <para>For larger packages, it is convenient to create log files instead of
    staring at the screen hoping to catch a particular error or warning. Log files
    are also useful for debugging and keeping records. The following command
    allows you to create an installation log. Replace &lt;command&gt; with the
    command you intend to execute.</para>

<screen><command>( &lt;command&gt; 2&gt;&amp;1 | tee compile.log &amp;&amp; exit $PIPESTATUS )</command></screen>

    <para><option>2&gt;&amp;1</option> redirects error messages to the same 
    location as standard output. The <command>tee</command> command allows 
    viewing of the output while logging the results to a file. The parentheses
    around the command run the entire command in a subshell and finally the
    <command>exit $PIPESTATUS</command> ensures the result of the 
    &lt;command&gt; is returned as the result and not the result of the 
    <command>tee</command> command.</para>

  </sect2>

</sect1>