LDP/LDP/howto/docbook/GNU-Build-System-HOWTO/GNU-Build-System-HOWTO.xml

<?xml version="1.0" encoding="ISO-8859-1"?>

<!--

The version history of this document, along with the comments are at the
end of the file. Last modification history is ...

$Id$

-->

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
     "/usr/share/sgml/docbook/xml-dtd-4.1.2/docbookx.dtd" [

  <!ENTITY make "<command>make</command>">
  <!ENTITY autoconf "<command>autoconf</command>">
  <!ENTITY automake "<command>automake</command>">
  <!ENTITY libtool "<command>libtool</command>">
  <!ENTITY libtoolize "<command>libtoolize</command>">
  <!ENTITY configure_cmd "<command>configure</command>">
  <!ENTITY m4 "<command>m4</command>">

  <!ENTITY makefile "<filename>Makefile</filename>">
  <!ENTITY makefile_in "<filename>Makefile.in</filename>">
  <!ENTITY makefile_am "<filename>Makefile.am</filename>">
  <!ENTITY configure_in "<filename>configure.in</filename>">
  <!ENTITY configure_file "<filename>configure</filename>">

  <!ENTITY cmdline "<prompt>[jrh@gbsbox ~/hw]$</prompt>">

  <!ENTITY howto "http://www.tldp.org/HOWTO/">
  <!ENTITY mini-howto "http://www.tldp.org/HOWTO/mini/">
  <!ENTITY gnu "http://www.gnu.org/">

]>

<article>

<articleinfo>

  <!-- Use "HOWTO", "mini HOWTO", "FAQ" in title, if appropriate -->
  <title>GNU-Build-System HOWTO</title>
  <titleabbrev>GBS-HOWTO</titleabbrev>

  <copyright>
    <year>2003</year>
    <holder>Mark Hoebeke</holder>
    <holder>Y Giridhar Appaji Nag</holder>
  </copyright>

  <authorgroup>

    <author>
      <firstname>Giridhar</firstname>
      <othername>Appaji Nag</othername>
      <surname>Y</surname>
      <affiliation>
        <address>
          <email>yganag{at}users{dot}sf{dot}net</email>
        </address>
      </affiliation>
    </author>

    <author>
      <firstname>Mark</firstname>
      <othername></othername>
      <surname>Hoebeke</surname>
      <affiliation>
        <address>
          <email>mark{dot}hoebeke{at}orange{dot}fr</email>
        </address>
      </affiliation>
    </author>

  </authorgroup>

  <!-- All dates specified in ISO "YYYY-MM-DD" format -->
  <pubdate>None Yet!</pubdate>

  <!-- Most recent revision goes at the top; list in descending order -->
  <revhistory>

    <revision>
      <revnumber>0.1</revnumber>
      <date>2003-11-05</date>
      <authorinitials>mh</authorinitials>
      <revremark>first formatting of consensus TOC</revremark>
    </revision>

  </revhistory>

  <!-- Provide a good abstract; a couple of sentences is sufficient -->
  <abstract>
    <para>

      This HOWTO aims to help beginning developers to leverage the power
      the the GNU Build System (GBS); The GBS is composed of well-known
      tools such as &make; and of less-used utilities such as
      &autoconf;, &automake; or &libtool;. The primary goal of the HOWTO
      is to ring developers up to speed with each of these tools, and,
      at another level to explain some of their inner workings.

    </para>

    <para>

      Document last updated $Date$.

    </para>

  </abstract>

</articleinfo>

<!-- Content follows...include introduction, license information -->
<sect1 id="introduction">

  <title>Introduction</title>

  <sect2 id="about-howto">

    <title>About this HOWTO</title>

    <para>About this HOWTO.</para>

  </sect2>

  <sect2 id="latest-version">

    <title>Keeping up-to-date</title>

    <para>

      New versions of this document that are released would be available
      from The LDP website and its mirrors. Since a few mirrors are
      broken or not up-to-date, it is highly recommended that the latest
      released version be accessed from <ulink
      url="&howto;GNU-Build-System-HOWTO/">
      http://www.tldp.org/HOWTO/GNU-Build-System-HOWTO/</ulink>. The
      latest in-progress version of this document is available at the
      <ulink
      url="http://www.pratapgarh.com/appaji/interests/freedom-sw/gbsh.html">
      GNU-Build-System HOWTO home page</ulink>.

    </para>

  </sect2>

  <!-- Legal Sections -->
  <sect2 id="license">

    <title>Document license</title>

    <!-- The LDP recommends, but doesn't require, the GFDL --> 
    <para>

      This document, the <emphasis>GNU-Build-System HOWTO</emphasis>, is
      distributed under the terms of the <citetitle>GNU General Public
      License</citetitle>. The word <emphasis>program</emphasis> in the
      license is to be interpreted as <emphasis>document</emphasis>.

    </para>

    <para>

      This program is free software; you can redistribute it and/or
      modify it under the terms of the <link linkend="gnu-gpl">
      <citetitle>GNU General Public License</citetitle></link> as
      published by the Free Software Foundation; either version 2 of the
      License, or (at your option) any later version. A copy of the
      license is available at <ulink
      url="http://www.gnu.org/licenses/gpl.txt">
      http://www.gnu.org/licenses/gpl.txt</ulink> and can be found in
      <xref linkend="gnu-gpl"/>.

    </para>

    <para>

      You should have received a copy of the GNU General Public License
      along with this program; if not, write to the Free Software
      Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
      02111-1307 USA

    </para>

  </sect2>

  <sect2 id="disclaimer">

    <title>Disclaimer</title>

    <para>

      This program is distributed in the hope that it will be useful,
      but WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
      General Public License for more details.

    </para>

    <para>

      All copyrights are held by their by their respective owners,
      unless specifically noted otherwise.  Use of a term in this
      document should not be regarded as affecting the validity of any
      trademark or service mark.  Naming of particular products or
      brands should not be seen as endorsements.

    </para>

  </sect2>

</sect1>

<sect1 id="overview">

  <title>The GBS-HOWTO at a glance</title>
  <para>
      
    The GNU Build System encompasses a vast number of components
    assisting the developer in every stage of the
    compile/configure/distribute process. Projects using the whole suite
    of the GBS are recognizable by the ease with which they are
    installed. Basically the ubiquitous "<command>./configure && make &&
    make install</command>" triplet does the trick. This HOWTO aims to
    take the reader step by step through the stages turning a set of
    source files into a "project" conforming to this GBS mantra. To be
    able to follow the explanations given in this HOWTO, the reader is
    expected to be familiar with the basics of using a compiler to build
    executables from source files.

  </para>

  <para>

    A first part of this HOWTO (<xref linkend="hello-gbs"/>) will work
    through each of these components in turn using a toy example.  This
    will acquaint the reader with the basic usage patterns of building
    &makefile;s to automate most if not all of a project's source code
    compilation thanks to the &make; command. This will also highlight
    the need to rely on other tools to ensure that compilation will
    perform correctly on most flavors of Unix (including Linux of
    course). Hence, the first step is to let &autoconf; take care of
    platform-specific parameters by building an appropriate
    &configure_file; script by the &autoconf; command.  We'll also
    transform our &makefile; into a &makefile_in; which abstracts away
    the platform related compilation issues. Though greatly automated,
    this step still requires some tweaking, but that's what this HOWTO's
    been made for after all. The final step to build a well-behaved and
    distributable software project is to supply &make; with a set of
    standard targets and to use a set of thoroughly tested recipes to
    build them. This is where &automake; comes into play. Starting from
    a high-level description of the project's components (source files,
    binaries to be built, documentation, additional data files) found in
    a &makefile_am;, &automake; is capable of generating a suitable
    &makefile_in;. So that's it? Now we've got our GBS compliant project
    architecture, isn't it? Indeed, but our toolkit would be incomplete
    if we omitted to mention &libtool;. This last component favors the
    use of program libraries (sets of related object files grouped into
    a single archive). These libraries can the be used by all
    executables of a project, and in some cases, without being copied in
    every single executable. Ways of building these libraries vary much
    from platform to platform, but luckily, &libtool; now greatly
    simplifies this process, lifting this burden from the programmer.

  </para>

  <para>

    After this entry-level guided tour, a real world programming project
    will be subjected to the whole slew of procedures just described
    (<xref linkend="real-example"/>).  There's no such thing as a real
    world example to expose some of the hurdles that inevitably show up
    when things get a bit more complex.

  </para>

  <para>

    To the survivors of the former section, we recommend the more
    in-depth look at the inner workings of all the GBS components
    provided in <xref linkend="inside-look"/>. Just for starters, it
    describes the innards of the &make; before covering a rather
    ill-known macro programming language, <command>m4</command> upon
    which several of the GBS tools are built. It then scrutinizes
    &autoconf;, &automake; and &libtool; to explain their what's and
    how's.
        
  </para>

  <para>

    The last section of the HOWTO covers the installation of the GBS
    components, either from pre-packaged files specific to Linux
    distributions, or from source <filename>.tar.gz</filename> archives
    (also called <emphasis>tarballs</emphasis>).

  </para>

</sect1>

<sect1 id="hello-gbs">

  <title>Hello build system!</title>

  <para>

    This section of the document introduces the build tools and explains
    how to use them. Though the treatment would not be in depth, it
    should help you understand the files that these tools operate on.
    After going though this section of the HOWTO, you would be able to
    read the documents provided here as references and experiment with
    the features that these tools have to offer.

  </para>

  <sect2 id="hello-make">

    <title>Hello GNU &make;!</title>

    <para>

      If you are reading this document, it is possible that you already
      have prior experience with the &make; utility. However, any
      discussion of the build system would be incomplete without a
      mention of &make;.

    </para>

    <sect3 id="make-whatis">
      <title>What is &make;</title>

      <para>
      
        &make; is a utility for automatic compilation of programs. It is
        usually used in projects to find out if the files that a certain
        <quote>target</quote> depends on have changed, and re-generates
        the target.

      </para>
    </sect3>

    <sect3 id="make-example">
      <title>&make; in action</title>

      <para>

        A very minimal &makefile; would look like:

      </para>

<screen>
&cmdline; <userinput>cat Makefile</userinput>

foo: foo.c
        gcc -o foo foo.c

&cmdline;
</screen>

      <para>

        The target in this &makefile; is <filename>foo</filename> and it
        depends on the <filename>foo.c</filename> dependency. The
        second line tells make how to build the target in case the
        dependency changes.

      </para>

      <para>

        A slightly more useful example would be:

      </para>

<screen>
&cmdline; <userinput>cat Makefile</userinput>

default: hw

hw: hello.o world.o
      gcc -o hw hello.o world.o -lm

hello.o: hello.c hello.h
      gcc -c hello.c

world.o: world.c world.h
      gcc -c world.c

clean:
      rm -f hw hello.o world.o

&cmdline;
</screen>

      <para>

        The target in this &makefile; (which is the first target that
        appears in the &makefile;) is <literal>default</literal>.
        <literal>default</literal> depends on <literal>hw</literal>
        which in-turn depends on <filename>hello.o</filename> and
        <filename>world.o</filename>.  These can be <quote>made</quote>
        using the rules that have been specified for them.  For example,
        <filename>hello.o</filename> is created using the command
        <command>gcc -c hello.c</command> whenever
        <filename>hello.c</filename> or <filename>hello.h</filename> are
        modified.

      </para>

      <para>

        The other target <literal>clean</literal> can be invoked
        explicitly to remove the target files that have been
        generated.

      </para>

<screen>
&cmdline; <userinput>make clean</userinput>
rm -f hw hello.o world.o

&cmdline;
</screen>

      <para>

        A &makefile; can also be written using variables and wild-cards
        making it easy to modify and maintain. For example, the above
        &makefile; can be re-written as:

      </para>

<screen>
&cmdline; <userinput>cat Makefile</userinput>

TARGET = hw
OBJS = hello.o world.o
CC = gcc
CCOPTS = -c
LOPTS = -lm

all: $(TARGET)

$(TARGET): $(OBJS)
        $(CC) -o $@ $(OBJS) $(LOPTS)

%.o: %.c %.h
        $(CC) $(CCOPTS) $<

clean:
        rm -rf $(TARGET) $(OBJS)

&cmdline;
</screen>

      <para>

        Every <literal>$(VARIABLE)</literal> in the
        &makefile; is replaced with its value.  The
        generic rule <literal>%.o: %.c %.h</literal> <footnote> <para>
        In general, one source file would depend on more than one
        header file and the dependency rule is not as simple as this.
        It is infact difficult to keep track of dependencies on header
        files and their dependencies with nested includes.  There are
        ways of handling this (see the manual page of
        <command>makedepend</command> on
        your Linux machine and the <option>-M</option> option to <command>gcc</command>), but using
        &automake; makes this a cake-walk.  </para> </footnote> says that
        each <filename>.o</filename> file is dependent on the
        corresponding <filename>.c</filename> and the
        <filename>.h</filename> files. <literal>$@</literal> refers to
        the current target and <literal>$&lt</literal> refers to the
        first one among the list of dependencies of the current
        target.  Note that this version of the
        &makefile; does not need a lot of
        modifications if a single source file and the corresponding
        header files are added.

      </para>

      <para>

        GNU &make; provides several other useful features like the VPATH
        directive to locate the source files that are not co-located
        with the &makefile;, facility for sophisticated wildcards, etc.
        These are described in the <link
        linkend="resources"><citetitle>official GNU &make;
        manual</citetitle></link>.

      </para>

    </sect3>

    <sect3 id="make-gnumakefile">
      <title>A GNU &makefile;</title>

      <para>

        A &makefile; that goes with software packages, and follows the
        GNU &makefile; conventions has a few standard targets and
        provides useful and commonly used functionality like:

      </para>

      <itemizedlist>
        <listitem>
          <para>
            <literal>all</literal>: to build the package
          </para>
        </listitem>

        <listitem>
          <para>

            <literal>clean</literal>: which removes all the generated
            files

          </para>
        </listitem>

        <listitem>
          <para>

            <literal>tags</literal>: generates the TAGS file for source
            browsing

          </para>
        </listitem>

        <listitem>
          <para>

            <literal>check</literal>: which executes any automated test
            cases that have been included with the package.

          </para>
        </listitem>

        <listitem>
          <para>

            <literal>dist</literal>: creates a .tar.gz distribution of
            the software package.

          </para>
        </listitem>

        <listitem>
          <para>

            <literal>uninstall</literal>: removes the files that have
            been installed

          </para>
        </listitem>
      </itemizedlist>

      <para>

        and many more ...

      </para>

      <para>

        Writing the dependencies and rules for these targets is a
        non-trivial task and involves some effort. &automake; solves
        this problem by generating all the standard targets.

      </para>

    </sect3>

  </sect2>

  <sect2 id="hello-autoconf">

    <title>Hello &autoconf;!</title>

    <para></para>

  </sect2>

  <sect2 id="hello-automake">

    <title>Hello &automake;!</title>

    <para></para>

  </sect2>

  <sect2 id="hello-libtool">

    <title>Hello &libtool;!</title>

    <para></para>

  </sect2>

</sect1>

<sect1 id="real-example">

  <title>Back to the real world</title>

  <sect2 id="example-make">

    <title>A real GNU &make; example</title>

    <para></para>

  </sect2>

  <sect2 id="example-autoconf">

    <title>A real &autoconf; example</title>

    <para></para>

  </sect2>

  <sect2 id="example-automake">

    <title>A real &automake; example</title>

    <para></para>

  </sect2>

  <sect2 id="example-libtool">

    <title>A real &libtool; example</title>

    <para></para>

  </sect2>

  <sect2 id="other-tools">

    <title>Accompanying tools</title>

    <para>
    
      A note on <command>makedepend</command>,
      <command>autoheader</command>, <command>autoscan</command>,
      <command>ifnames</command>, <command>aclocal</command>,
      <command>autoproject</command>, <command>autoupdate</command>,
      <command>autoreconf</command> etc.

    </para>

  </sect2>

</sect1>

<sect1 id="inside-look">

  <title>An inside look</title>

  <sect2 id="inside-make">

    <title>Inside GNU &make;</title>

    <para></para>

  </sect2>

  <sect2 id="inside-m4">

    <title>The &m4; macro processor</title>

    <para></para>

  </sect2>

  <sect2 id="inside-autoconf">

    <title>Inside &autoconf;</title>

    <para></para>

  </sect2>

  <sect2 id="inside-automake">

    <title>Inside &automake;</title>

    <para></para>

  </sect2>

  <sect2 id="inside-libtool">

    <title>Inside &libtool;</title>

    <para></para>

  </sect2>

</sect1>

<sect1 id="tools-install">

  <title>Installing the tools</title>

  <sect2 id="distro-install">

    <title>From GNU/Linux distribution packages</title>

    <para></para>

  </sect2>

  <sect2 id="source-install">

    <title>Installation from source</title>

    <para></para>

  </sect2>

</sect1>

<sect1 id="final-words">

  <title>Final Words</title>

  <!-- Translations -->
  <sect2 id="translations">

  <title>Translations</title>

    <para></para>

<!--
  <para>
   Pointers to available translations are nice.
   Also, your translators tend to give very important inputs.
  </para>

  <itemizedlist>
    <listitem>
      <para>
       <ulink url="http://tldp.org/">French Translation</ulink>
       provided by Individual <email>someone (at) somewhere.fr</email>
      </para>
    </listitem>
    <listitem>
      <para>
       <ulink url="http://tldp.org/">German Translation</ulink>
       provided by Individual <email>someone (at) somewhere.de</email>
      </para>
    </listitem>
  </itemizedlist>
-->

  </sect2>

  <!-- Feedback -->
  <sect2 id="feedback">

    <title>Comments and Suggestions</title>

    <para>

      Comments and suggestions regarding this document may be sent to
      <email>mark{dot}hoebeke{at}orange{dot}fr</email> and
      <email>yganag{at}users{dot}sf{dot}net</email>. Please point out
      any mistakes, omissions, broken links and possible improvements so
      that they can be incorporated in future revisions of the document.
      In case you have additions and improvements that would change
      major portions of the document, it would be great if you could
      send them as a patch against the latest DocBook/XML version.

    </para>

  </sect2>

  <!-- Give credit where credit is due...very important -->
  <sect2 id="thanks">

    <title>Acknowledgements</title>

    <para>
    
      The authors of this document have the pleasure of acknowledging
      the following people who have contributed to this document by
      sending in comments and suggestions for improvements.

  <!-- Please scramble addresses; help prevent spam/email harvesting -->
<!--
  <itemizedlist>
    <listitem> 
      <para>Individual 1 <email>someone1 (at) somewhere.org</email></para>
    </listitem>
    <listitem> 
      <para>Individual 2 <email>someone2 (at) somewhere.org</email></para>
    </listitem>
  </itemizedlist>
-->

    </para>

  </sect2>

</sect1>

<sect1 id="resources">

  <title>References and Resources</title>

  <itemizedlist>

    <listitem>
      <para>

        <ulink url="http://www.st-andrews.ac.uk/~iam/docs/tutorial.html">
        Learning the GNU Development Tools</ulink> by Eleftherios
        Gkioulekas is a good tutorial to understand the GNU build
        system and the documentation files associated with GNU style
        packages.

      </para>
    </listitem>

    <listitem>
      <para>

        The <quote>autotools</quote> referred to in the above tutorial
        can be downloaded from <ulink
        url="ftp://ftp.ugcs.caltech.edu/pub/elef/autotools">
        ftp://ftp.ugcs.caltech.edu/pub/elef/autotools</ulink>. Though
        the author seems to be planning a rewrite, it is worth taking
        a look at.

      </para>
    </listitem>

    <listitem>
      <para>

        <ulink url="http://www.mv.com/ipusers/vanzandt/">autoproject:
        </ulink> In the authors words, <quote>autoproject - a script to
        start a programming project using &autoconf;, &automake;, and
        optionally a command line parser generator</quote>

      </para>
    </listitem>

    <listitem>
      <para>

        <ulink url="http://www.newriders.com/autoconf">GNU Autoconf,
        Automake and Libtool</ulink> is probably the best guide for
        mastering these tools.  You can also read it online at <ulink
        url="http://sources.redhat.com/autobook/download.html">
        http://sources.redhat.com/autobook/download.html</ulink>

      </para>
    </listitem>

    <listitem>
      <para>

        The official GNU &make; manual <ulink
        url="&gnu;manual/make/index.html">
        http://www.gnu.org/manual/make/index.html</ulink>

      </para>
    </listitem>

    <listitem>
      <para>

        The official &autoconf; manual <ulink
        url="&gnu;manual/autoconf/index.html">
        http://www.gnu.org/manual/autoconf/index.html</ulink>

      </para>
    </listitem>

    <listitem>
      <para>

        The official &automake; manual <ulink
        url="&gnu;manual/automake/index.html">
        http://www.gnu.org/manual/automake/index.html</ulink>

      </para>
    </listitem>

    <listitem>
      <para>

        The official &libtool; manual <ulink
        url="&gnu;manual/libtool/index.html">
        http://www.gnu.org/manual/libtool/index.html</ulink>

      </para>
    </listitem>

    <listitem>
      <para>

        The official &m4; manual <ulink url="&gnu;manual/m4/index.html">
        http://www.gnu.org/manual/m4/index.html</ulink>

      </para>
    </listitem>

  </itemizedlist>

</sect1>

<appendix id="gnu-gpl">

  <appendixinfo>

  <pubdate>Version 2, June 1991</pubdate>

  <copyright>

    <year>1989, 1991</year>
    <holder>Free Software Foundation, Inc.</holder>

  </copyright>

  <legalnotice>

    <para>

      <address>
        Free Software Foundation, Inc. 
        <street>59 Temple Place, Suite 330</street>, 
        <city>Boston</city>, 
        <state>MA</state> 
        <postcode>02111-1307</postcode>
        <country>USA</country>
      </address>.

    </para>

    <para>

      Everyone is permitted to copy and distribute verbatim copies of
      this license document, but changing it is not allowed.

    </para>

  </legalnotice>

  <releaseinfo>Version 2, June 1991</releaseinfo>

  </appendixinfo>

  <title>GNU General Public License</title>
  <titleabbrev>GNU-GPL</titleabbrev>

  <sect1 id="gpl-preamble">

    <title>Preamble</title>

    <para>
    
      The licenses for most software are designed to take away your
      freedom to share and change it. By contrast, the GNU General
      Public License is intended to guarantee your freedom to share and
      change free software - to make sure the software is free for all
      its users.  This General Public License applies to most of the
      Free Software Foundation's software and to any other program whose
      authors commit to using it. (Some other Free Software Foundation
      software is covered by the GNU Library General Public License
      instead.) You can apply it to your programs, too.

    </para>

    <para>
    
      When we speak of free software, we are referring to freedom, not
      price.  Our General Public Licenses are designed to make sure that
      you have the freedom to distribute copies of free software (and
      charge for this service if you wish), that you receive source code
      or can get it if you want it, that you can change the software or
      use pieces of it in new free programs; and that you know you can
      do these things.

    </para>

    <para>
    
      To protect your rights, we need to make restrictions that forbid
      anyone to deny you these rights or to ask you to surrender the
      rights. These restrictions translate to certain responsibilities
      for you if you distribute copies of the software, or if you modify
      it.

    </para>

    <para>
    
      For example, if you distribute copies of such a program, whether
      gratis or for a fee, you must give the recipients all the rights
      that you have. You must make sure that they, too, receive or can
      get the source code. And you must show them these terms so they
      know their rights.

    </para>

    <para>

      We protect your rights with two steps:

      <orderedlist>

        <listitem>

          <para>copyright the software, and </para>

        </listitem>

        <listitem>

          <para>
          
            offer you this license which gives you legal permission to
            copy, distribute and/or modify the software.
          
          </para>

        </listitem>

        </orderedlist>

    </para>

    <para>
    
      Also, for each author's protection and ours, we want to make
      certain that everyone understands that there is no warranty for
      this free software. If the software is modified by someone else
      and passed on, we want its recipients to know that what they have
      is not the original, so that any problems introduced by others
      will not reflect on the original authors' reputations.

    </para>

    <para>
    
      Finally, any free program is threatened constantly by software
      patents.  We wish to avoid the danger that redistributors of a
      free program will individually obtain patent licenses, in effect
      making the program proprietary. To prevent this, we have made it
      clear that any patent must be licensed for everyone's free use or
      not licensed at all.

    </para>

    <para>
    
      The precise terms and conditions for copying, distribution and
      modification follow.

    </para>

  </sect1>

  <sect1 id="gpl-terms">

    <title>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</title>
    <sect2>

      <title>Section 0</title>

      <para>
        
        This License applies to any program or other work which contains
        a notice placed by the copyright holder saying it may be
        distributed under the terms of this General Public License.  The
        "Program", below, refers to any such program or work, and a
        <quote>work based on the Program </quote> means either the
        Program or any derivative work under copyright law: that is to
        say, a work containing the Program or a portion of it, either
        verbatim or with modifications and/or translated into another
        language. (Hereinafter, translation is included without
        limitation in the term <quote>modification </quote>.) Each
        licensee is addressed as <quote>you</quote>.

      </para>

      <para>
        
        Activities other than copying, distribution and modification are
        not covered by this License; they are outside its scope.  The
        act of running the Program is not restricted, and the output
        from the Program is covered only if its contents constitute a
        work based on the Program (independent of having been made by
        running the Program). Whether that is true depends on what the
        Program does.

      </para>

    </sect2>

    <sect2 id="gpl-section1">

      <title>Section 1</title>

      <para>
        
        You may copy and distribute verbatim copies of the Program's
        source code as you receive it, in any medium, provided that you
        conspicuously and appropriately publish on each copy an
        appropriate copyright notice and disclaimer of warranty; keep
        intact all the notices that refer to this License and to the
        absence of any warranty; and give any other recipients of the
        Program a copy of this License along with the Program.

      </para>

      <para>
        
        You may charge a fee for the physical act of transferring a
        copy, and you may at your option offer warranty protection in
        exchange for a fee.

      </para>

    </sect2>

    <sect2 id="gpl-section2">

      <title>Section 2</title>

      <para>
      
        You may modify your copy or copies of the Program or any portion
        of it, thus forming a work based on the Program, and copy and
        distribute such modifications or work under the terms of <link
        linkend="gpl-section1">Section 1 </link> above, provided that
        you also meet all of these conditions:

        <orderedlist>

          <listitem>

            <para>
            
              You must cause the modified files to carry prominent
              notices stating that you changed the files and the date of
              any change.

            </para>

          </listitem>

          <listitem>

            <para>
            
              You must cause any work that you distribute or publish,
              that in whole or in part contains or is derived from the
              Program or any part thereof, to be licensed as a whole at
              no charge to all third parties under the terms of this
              License.

          </para>

        </listitem>

        <listitem>

          <para>
          
            If the modified program normally reads commands
            interactively when run, you must cause it, when started
            running for such interactive use in the most ordinary way,
            to print or display an announcement including an appropriate
            copyright notice and a notice that there is no warranty (or
            else, saying that you provide a warranty) and that users may
            redistribute the program under these conditions, and telling
            the user how to view a copy of this License. 

              <note>

                <title>Exception:</title>

                <para>

                  If the Program itself is interactive but does not
                  normally print such an announcement, your work based
                  on the Program is not required to print an
                  announcement.) 

                </para>

              </note>

            </para>

          </listitem>
        </orderedlist>

      </para>

      <para>

        These requirements apply to the modified work as a whole. If
        identifiable sections of that work are not derived from the
        Program, and can be reasonably considered independent and
        separate works in themselves, then this License, and its terms,
        do not apply to those sections when you distribute them as
        separate works. But when you distribute the same sections as
        part of a whole which is a work based on the Program, the
        distribution of the whole must be on the terms of this License,
        whose permissions for other licensees extend to the entire
        whole, and thus to each and every part regardless of who wrote
        it.

      </para>

      <para>
    
        Thus, it is not the intent of this section to claim rights or
        contest your rights to work written entirely by you; rather, the
        intent is to exercise the right to control the distribution of
        derivative or collective works based on the Program.

      </para>

      <para>
    
        In addition, mere aggregation of another work not based on the
        Program with the Program (or with a work based on the Program)
        on a volume of a storage or distribution medium does not bring
        the other work under the scope of this License.

      </para>

    </sect2>

    <sect2 id="gpl-section3">

      <title>Section 3</title>

      <para>
      
        You may copy and distribute the Program (or a work based on it,
        under <link linkend="gpl-section2">Section 2 </link> in object
        code or executable form under the terms of <link
        linkend="gpl-section1">Sections 1 </link> and <link
        linkend="gpl-section2">2 </link> above provided that you also do
        one of the following:

        <orderedlist>

          <listitem>

            <para>
            
              Accompany it with the complete corresponding
              machine-readable source code, which must be distributed
              under the terms of Sections 1 and 2 above on a medium
              customarily used for software interchange; or,

            </para>

          </listitem>

          <listitem>

            <para>
            
              Accompany it with a written offer, valid for at least
              three years, to give any third party, for a charge no more
              than your cost of physically performing source
              distribution, a complete machine-readable copy of the
              corresponding source code, to be distributed under the
              terms of Sections 1 and 2 above on a medium customarily
              used for software interchange; or,

            </para>

          </listitem>

          <listitem>

            <para>
            
              Accompany it with the information you received as to the
              offer to distribute corresponding source code. (This
              alternative is allowed only for noncommercial distribution
              and only if you received the program in object code or
              executable form with such an offer, in accord with
              Subsection b above.)

            </para>

          </listitem>

        </orderedlist>

      </para>

      <para>
      
        The source code for a work means the preferred form of the work
        for making modifications to it. For an executable work, complete
        source code means all the source code for all modules it
        contains, plus any associated interface definition files, plus
        the scripts used to control compilation and installation of the
        executable. However, as a special exception, the source code
        distributed need not include anything that is normally
        distributed (in either source or binary form) with the major
        components (compiler, kernel, and so on) of the operating system
        on which the executable runs, unless that component itself
        accompanies the executable.

      </para>

      <para>
      
        If distribution of executable or object code is made by offering
        access to copy from a designated place, then offering equivalent
        access to copy the source code from the same place counts as
        distribution of the source code, even though third parties are
        not compelled to copy the source along with the object code.

      </para>

    </sect2>

    <sect2 id="gpl-section4">

      <title>Section 4</title>

      <para>
      
        You may not copy, modify, sublicense, or distribute the Program
        except as expressly provided under this License. Any attempt
        otherwise to copy, modify, sublicense or distribute the Program
        is void, and will automatically terminate your rights under this
        License. However, parties who have received copies, or rights,
        from you under this License will not have their licenses
        terminated so long as such parties remain in full compliance.

      </para>

    </sect2>

    <sect2 id="gpl-section5">

      <title>Section 5</title>

      <para>
      
        You are not required to accept this License, since you have not
        signed it. However, nothing else grants you permission to modify
        or distribute the Program or its derivative works.  These
        actions are prohibited by law if you do not accept this License.
        Therefore, by modifying or distributing the Program (or any work
        based on the Program), you indicate your acceptance of this
        License to do so, and all its terms and conditions for copying,
        distributing or modifying the Program or works based on it.

      </para>

    </sect2>

    <sect2 id="gpl-section6">

      <title>Section 6</title>

      <para>
      
        Each time you redistribute the Program (or any work based on the
        Program), the recipient automatically receives a license from
        the original licensor to copy, distribute or modify the Program
        subject to these terms and conditions. You may not impose any
        further restrictions on the recipients' exercise of the rights
        granted herein. You are not responsible for enforcing compliance
        by third parties to this License.

      </para>

    </sect2>

    <sect2 id="gpl-section7">

      <title>Section 7</title>

      <para>
      
        If, as a consequence of a court judgment or allegation of patent
        infringement or for any other reason (not limited to patent
        issues), conditions are imposed on you (whether by court order,
        agreement or otherwise) that contradict the conditions of this
        License, they do not excuse you from the conditions of this
        License. If you cannot distribute so as to satisfy
        simultaneously your obligations under this License and any other
        pertinent obligations, then as a consequence you may not
        distribute the Program at all. For example, if a patent license
        would not permit royalty-free redistribution of the Program by
        all those who receive copies directly or indirectly through you,
        then the only way you could satisfy both it and this License
        would be to refrain entirely from distribution of the Program.

      </para>

      <para>
      
        If any portion of this section is held invalid or unenforceable
        under any particular circumstance, the balance of the section is
        intended to apply and the section as a whole is intended to
        apply in other circumstances.

      </para>

      <para>
      
        It is not the purpose of this section to induce you to infringe
        any patents or other property right claims or to contest
        validity of any such claims; this section has the sole purpose
        of protecting the integrity of the free software distribution
        system, which is implemented by public license practices. Many
        people have made generous contributions to the wide range of
        software distributed through that system in reliance on
        consistent application of that system; it is up to the
        author/donor to decide if he or she is willing to distribute
        software through any other system and a licensee cannot impose
        that choice.

      </para>

      <para>
      
        This section is intended to make thoroughly clear what is
        believed to be a consequence of the rest of this License.

      </para>

    </sect2>

    <sect2 id="gpl-section8">

      <title>Section 8</title>

      <para>
      
        If the distribution and/or use of the Program is restricted in
        certain countries either by patents or by copyrighted
        interfaces, the original copyright holder who places the Program
        under this License may add an explicit geographical distribution
        limitation excluding those countries, so that distribution is
        permitted only in or among countries not thus excluded. In such
        case, this License incorporates the limitation as if written in
        the body of this License.

      </para>

    </sect2>

    <sect2 id="gpl-section9">

      <title>Section 9</title>

      <para>
      
        The Free Software Foundation may publish revised and/or new
        versions of the General Public License from time to time. Such
        new versions will be similar in spirit to the present version,
        but may differ in detail to address new problems or concerns.

      </para>

      <para>
      
        Each version is given a distinguishing version number. If the
        Program specifies a version number of this License which applies
        to it and "any later version", you have the option of following
        the terms and conditions either of that version or of any later
        version published by the Free Software Foundation. If the
        Program does not specify a version number of this License, you
        may choose any version ever published by the Free Software
        Foundation.

      </para>

    </sect2>

    <sect2 id="gpl-section10">

      <title>Section 10</title>

      <para>
      
        If you wish to incorporate parts of the Program into other free
        programs whose distribution conditions are different, write to
        the author to ask for permission. For software which is
        copyrighted by the Free Software Foundation, write to the Free
        Software Foundation; we sometimes make exceptions for this. Our
        decision will be guided by the two goals of preserving the free
        status of all derivatives of our free software and of promoting
        the sharing and reuse of software generally.

      </para>

    </sect2>

    <sect2 id="gpl-warranty">

      <title>NO WARRANTY Section 11</title>

      <para>
      
        BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
        WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
        LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
        HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
        WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
        BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
        AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
        QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
        PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
        SERVICING, REPAIR OR CORRECTION.

      </para>

    </sect2>

    <sect2 id="gpl-section12">

      <title>Section 12</title>

      <para>
      
        IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
        WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
        MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
        LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
        INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
        INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS
        OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
        YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH
        ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
        ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
        
      </para>

      <para>END OF TERMS AND CONDITIONS</para>

    </sect2>

  </sect1>

  <sect1 id="gpl-apply">

    <title>How to Apply These Terms to Your New Programs</title>

    <para>

      If you develop a new program, and you want it to be of the
      greatest possible use to the public, the best way to achieve this
      is to make it free software which everyone can redistribute and
      change under these terms.

    </para>

    <para>

      To do so, attach the following notices to the program.  It is
      safest to attach them to the start of each source file to most
      effectively convey the exclusion of warranty; and each file should
      have at least the "copyright" line and a pointer to where the full
      notice is found.

    </para>

    <para>

      &lt;one line to give the program's name and a brief idea of what
      it does.&gt; Copyright (C) &lt;year&gt;    &lt;name of author&gt;

    </para>

    <para>

      This program is free software; you can redistribute it and/or
      modify it under the terms of the GNU General Public License as
      published by the Free Software Foundation; either version 2 of the
      License, or (at your option) any later version.

    </para>

    <para>

      This program is distributed in the hope that it will be useful,
      but WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      General Public License for more details.

    </para>

    <para>

      You should have received a copy of the GNU General Public License
      along with this program; if not, write to the Free Software
      Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
      02111-1307  USA

    </para>

    <para>

      Also add information on how to contact you by electronic and paper
      mail.

    </para>

    <para>

      If the program is interactive, make it output a short notice like
      this when it starts in an interactive mode:

    </para>

    <para>

      Gnomovision version 69, Copyright (C) year name of author
      Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
      `show w'.  This is free software, and you are welcome to
      redistribute it under certain conditions; type `show c' for
      details.

    </para>

    <para>

      The hypothetical commands `show w' and `show c' should show the
      appropriate parts of the General Public License.  Of course, the
      commands you use may be called something other than `show w' and
      `show c'; they could even be mouse-clicks or menu items--whatever
      suits your program.

    </para>

    <para>

      You should also get your employer (if you work as a programmer) or
      your school, if any, to sign a "copyright disclaimer" for the
      program, if necessary.  Here is a sample; alter the names:

    </para>

    <para>

      Yoyodyne, Inc., hereby disclaims all copyright interest in the
      program `Gnomovision' (which makes passes at compilers) written by
      James Hacker.

    </para>

    <para>

      &lt;signature of Ty Coon&gt;, 1 April 1989 Ty Coon, President of
      Vice

    </para>

    <para>

      This General Public License does not permit incorporating your
      program into proprietary programs.  If your program is a
      subroutine library, you may consider it more useful to permit
      linking proprietary applications with the library.  If this is
      what you want to do, use the GNU Library General Public License
      instead of this License.

    </para>

  </sect1>

</appendix>

</article>

<!--

$Log$
Revision 1.8  2003/11/20 14:20:30  appaji
Major structure re-org, Change titles of a few sections

Revision 1.7  2003/11/20 11:32:09  appaji
Proper copyright, disclaimer of warranty WRT the GNU GPL

Revision 1.6  2003/11/20 10:40:17  appaji
Remove Id CVS keyword, Log CVS keyword to take care of history in the sources

Revision 1.5  2003/11/20 10:39:14  appaji
Format for 72 character lines

-->