shorewall_code/docs/Build.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article>
  <!--$Id$-->

  <articleinfo>
    <title>Building Shorewall from Git</title>

    <authorgroup>
      <author>
        <firstname>Tom</firstname>

        <surname>Eastep</surname>
      </author>
    </authorgroup>

    <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>

    <copyright>
      <year>2009</year>

      <year>2010</year>

      <holder>Thomas M. Eastep</holder>
    </copyright>

    <legalnotice>
      <para>Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU Free Documentation License, Version
      1.2 or any later version published by the Free Software Foundation; with
      no Invariant Sections, with no Front-Cover, and with no Back-Cover
      Texts. A copy of the license is included in the section entitled
      <quote><ulink url="GnuCopyright.htm">GNU Free Documentation
      License</ulink></quote>.</para>
    </legalnotice>
  </articleinfo>

  <note>
    <para>This information is provided primarily for Shorewall developers.
    Users are expected to install from pre-built tarballs or packages.</para>
  </note>

  <section>
    <title>Git Taxonomy</title>

    <para>The Shorewall Git tree at Sourceforge serves as the master
    repository for Shorewall 4.4 and later versions. It is not possible to
    simply export a directory from Git and run the
    <command>install.sh</command> script in that directory. A build step is
    required to produce a directory that is suitable for the
    <command>install.sh</command> script to run in.</para>

    <section>
      <title>trunk</title>

      <para>The development branch of each product is kept here.</para>

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

        <listitem>
          <para>Shorewall6</para>
        </listitem>

        <listitem>
          <para>Shorewall-lite</para>
        </listitem>

        <listitem>
          <para>Shorewall6-lite</para>
        </listitem>
      </itemizedlist>

      <para>There are also several other directories which are described in
      the following sub-sections.</para>

      <section>
        <title>trunk/docs</title>

        <para>The development release XML documents. Depending on the point in
        the release cycle, these documents may also apply to the current
        stable version. In that case, there is no docs directory in that
        release's directory in <emphasis
        role="bold">branches</emphasis>.</para>
      </section>

      <section>
        <title>trunk/web</title>

        <para>The files from the web site that are maintained in HTML format.
        are kept in this directory.</para>
      </section>

      <section>
        <title>trunk/manpages, trunk/manpages6, trunk/manpages-lite and
        trunk/manpages6-lite</title>

        <para>The development release XML manpages. Depending on the point in
        the release cycle, these documents may also apply to the current
        stable version.</para>
      </section>

      <section>
        <title>trunk/tools</title>

        <para>This is where the release and build tools are kept. There are
        two subordinate directories:</para>

        <variablelist>
          <varlistentry>
            <term>trunk/tools/build</term>

            <listitem>
              <para>Tools for building and uploading new releases.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>trunk/tools/web</term>

            <listitem>
              <para>Tools for publishing web content.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
    </section>
  </section>

  <section>
    <title>Build Tools</title>

    <para>As described above, the build tools are kept in <filename
    class="directory">trunk/tools/build.</filename> They are described in the
    following sections.</para>

    <section>
      <title>setversion</title>

      <para>The <command>setversion</command> script updates the version
      number in a directory. The script is run with the current working
      directory being <filename class="directory">trunk</filename>.</para>

      <blockquote>
        <para><command>setversion</command>
        <replaceable>version</replaceable></para>
      </blockquote>

      <para>The <replaceable>version</replaceable> may either be a minor
      version or a patch version.</para>
    </section>

    <section>
      <title>build44</title>

      <para>This is the script that builds Shorewall packages from Git.</para>

      <para>The script copies content from Git using the <command>git
      archive</command> command. It then uses that content to build the
      packages. In addition to the usual Gnu utilities, the following software
      is required:</para>

      <variablelist>
        <varlistentry>
          <term>rpmbuild (I use rpm version 4.4.2.3-20.3)</term>

          <listitem>
            <para>Required to build the RPM packages.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>xsltproc (libxslt -- I use version 1.1.24-19.1)</term>

          <listitem>
            <para>Required to convert the XML documents to other
            formats.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Docbook XSL Stylesheets (I use docbook-xsl-stylesheets version
          1.74.0-1.35)</term>

          <listitem>
            <para>Required to convert the XML documents to other
            formats.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Perl (I use Perl 5.10.0-62.17.1)</term>

          <listitem>
            <para>Required to massage some of the config files.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>xmlto (I use version 0.0.18-182.27)</term>

          <listitem>
            <para>Required to convert the XML manpages to manpages. Note that
            not all versions of xmlto will work (those released by Debian and
            Ubuntu, for example, do <emphasis>not</emphasis> work). If you
            find that xmlto fails, install
            tools<filename>/build/xmlto</filename> in <filename
            class="directory">/usr/local/bin</filename>.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>You should ensure that you have the latest script. The scripts
      change periodically as we move through the release cycles.</para>

      <para>The scripts may need to be modified to fit your particular
      environment. There are a number of variables that are set near the front
      of the script:</para>

      <variablelist>
        <varlistentry>
          <term>STYLESHEET</term>

          <listitem>
            <para>Must point to the XHTML docbook.xsl stylesheet from your
            Docbook XSL Stylesheets installation.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>LOGDIR</term>

          <listitem>
            <para>Directory where you want the build log placed. Defaults to
            the current working directory.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>RPMDIR</term>

          <listitem>
            <para>Points to your RPM directory .</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>DIR</term>

          <listitem>
            <para>Directory where you want the release to be built. Defaults
            to the current working directory.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>GIT</term>

          <listitem>
            <para>Shorewall GIT repository</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>The scripts assume that there will be a separete <firstterm>build
      directory</firstterm> per major release. To build a release, you cd to
      the appropriate directory and run the build script.</para>

      <para>The general form of the build command is:</para>

      <blockquote>
        <para><command>build44</command> [ -<replaceable>options</replaceable>
        ] <replaceable>release</replaceable> [ <replaceable>prior
        release</replaceable> ]</para>
      </blockquote>

      <para>where</para>

      <variablelist>
        <varlistentry>
          <term>opt<emphasis>i</emphasis>ons</term>

          <listitem>
            <para>are one of the following. If no options are given then all
            options are assumed</para>

            <variablelist>
              <varlistentry>
                <term>t</term>

                <listitem>
                  <para>build tar files</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>r</term>

                <listitem>
                  <para>build RPMs</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>c</term>

                <listitem>
                  <para>Build the shorewall package.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>l</term>

                <listitem>
                  <para>Build the shorewall-lite package.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>6</term>

                <listitem>
                  <para>Build the shorewall6 package.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>L</term>

                <listitem>
                  <para>Build the shorewall6-lite package.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>h</term>

                <listitem>
                  <para>Build the html document package.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>x</term>

                <listitem>
                  <para>Build the xml document package.</para>
                </listitem>
              </varlistentry>
            </variablelist>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis>release</emphasis></term>

          <listitem>
            <para>The release version to build. Must match the version in the
            associated Git path.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis>prior release</emphasis></term>

          <listitem>
            <para>The release to be used to generate patch files.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>Example 1 - Build Shorewall 4.3.7 and generate patches against
      4.3.6:</para>

      <blockquote>
        <para><command>build44 4.3.7 4.3.6</command></para>
      </blockquote>

      <para>Example 2 - Build Shorewall 4.2.7.1 Shorewall and generate patches
      against 4.2.7:</para>

      <blockquote>
        <para><command>build44 -trSc 4.3.7.1 4.3.7</command></para>
      </blockquote>
    </section>

    <section>
      <title>upload44</title>

      <para>This script is used to upload a release to lists.shorewall.net.
      The command is run in the build directory for the major release of the
      product.</para>

      <blockquote>
        <para><command>upload44</command> [
        -<replaceable>products</replaceable> ]
        <replaceable>release</replaceable></para>
      </blockquote>

      <para>where</para>

      <variablelist>
        <varlistentry>
          <term><emphasis>products</emphasis></term>

          <listitem>
            <para>specifes the products to upload. If not given, all products
            are uploaded. This option is generally given only when uploading a
            patch release.</para>

            <variablelist>
              <varlistentry>
                <term>c</term>

                <listitem>
                  <para>Upload the shorewall package.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>l</term>

                <listitem>
                  <para>Upload the shorewall-lite package.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>6</term>

                <listitem>
                  <para>Upload the shorewall6 package.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>L</term>

                <listitem>
                  <para>Upload the shorewall6-lite package.</para>
                </listitem>
              </varlistentry>
            </variablelist>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis>release</emphasis></term>

          <listitem>
            <para>The version number of the release to upload.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>Example 1 - Upload release 4.3.7:</para>

      <blockquote>
        <para><command>upload44 4.3.7</command></para>
      </blockquote>

      <para>Example 2 - Upload shorewall-perl-4.3.7.3:</para>

      <blockquote>
        <para><command>upload44 -p 4.3.7.3</command></para>
      </blockquote>
    </section>
  </section>
</article>