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>

      <year>2012</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, no Front-Cover Texts, and 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.
	    In addition to the below, it is also suggested to read the
	    <ulink url="https://gitlab.com/shorewall/tools/raw/master/files/shorewall-release-process.txt">README file</ulink>
	    located in the root directory of the tools repository.
    </para>
  </note>

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

    <para>The Shorewall Git tree at Gitlab 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>

    <para>My local git repositories are:</para>

    <section>
      <title>code (clone of Code)</title>

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

      <itemizedlist>
        <listitem>
          <para>Shorewall-core.</para>
        </listitem>

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

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

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

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

        <listitem>
          <para>Shorewall-init</para>
        </listitem>
      </itemizedlist>

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

    <section>
      <title>code/docs</title>

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

    <section>
      <title>release (Clone of Release)</title>

      <para>Added in Shorewall 4.4.22, this directory contains the files that
      contain release-dependent information (change.txt, releasenotes.txt,
      .spec files, etc). This is actually a symbolic link to ../release which
      has its own Git repository.</para>
    </section>

    <section>
      <title>testing (Clone of Testing)</title>

      <para> This directory contains the regression library files.</para>
    </section>

    <section>
      <title>tools (Clone of Tools)</title>

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

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

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

        <varlistentry>
          <term>tools/files</term>

          <listitem>
		  <para>Files that are used during the release process.
		  The license and readme files are also kept there.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>tools/testing</term>

          <listitem>
            <para>Tools for testing.</para>
          </listitem>
        </varlistentry>

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

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

    <section>
      <title>web (Clone of Web)</title>

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

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

    <para>As described above, the build tools are kept in <filename
    class="directory">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">release</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>build45, build46, and build</title>

      <para>These are the scripts that respectively build Shorewall 4.5,
      Shorewall 4.6 and Shorewall 5.[012] packages from Git.
      Build is actually a symlink to the current build script.</para>

      <para>The scripts copy content from Git using the <command>git
      archive</command> command. They then use that content to build the
      packages. In addition to the usual Gnu utilities, the following software
      is required:</para>

      <variablelist>
        <varlistentry>
          <term>rpmbuild</term>

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

        <varlistentry>
          <term>xsltproc (libxslt)</term>

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

        <varlistentry>
          <term>Docbook XSL Stylesheets</term>

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

        <varlistentry>
          <term>Perl</term>

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

        <varlistentry>
          <term>xmlto</term>

          <listitem>
            <para>Required to convert the XML manpages to manpages. Be sure
            that you have a recent version; I use 0.0.25.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>You should ensure that you have the latest scripts. 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 top
      of the file:</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 separate <firstterm>build
      directory</firstterm> per major release. Each build directory should
      contain the empty file <filename>shorewall-pkg.config</filename>; that
      file is no longer used but has been retained just as a guard against
      initiating a build in an unintended directory. 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>build</command>[<replaceable>xx</replaceable>] [ -<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 or more 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-core package.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>i</term>

                <listitem>
                  <para>Build the shorewall-init 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>s</term>

                <listitem>
                  <para>Build the shorewall 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.5.7 and generate patches against
      4.5.6:</para>

      <blockquote>
        <para><command>build45 4.5.7 4.5.6</command></para>
      </blockquote>

      <para>Example 2 - Build Shorewall 4.5.7.1 Shorewall-core and generate
      patches against 4.5.7:</para>

      <blockquote>
        <para><command>build45 -trc 4.5.7.1 4.5.7</command></para>
      </blockquote>
    </section>

    <section>
      <title>upload</title>

      <para>This script is used to upload a release to https://shorewall.org. The
      command is run in the build directory for the minor release of the
      product.</para>

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

      <para>where</para>

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

          <listitem>
            <para>specifies 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-core package.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>l</term>

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

              <varlistentry>
                <term>i</term>

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

              <varlistentry>
                <term>s</term>

                <listitem>
                  <para>Upload the shorewall 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>upload 4.3.7</command></para>
      </blockquote>

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

      <blockquote>
        <para><command>upload -c 4.3.7.3</command></para>
      </blockquote>
    </section>

    <section>
      <title>install.sh files</title>

      <para>Each product includes an install script
      (<filename>install.sh</filename>) that may be used to install the
      product on a machine or into a directory.</para>

      <para>By default, the scripts install the corresponding product into
      "/'; you can direct them to install into an empty existing directory by
      setting an environmental variable:</para>

      <itemizedlist>
        <listitem>
          <para>DESTDIR (release 4.4.10 and later)</para>
        </listitem>

        <listitem>
          <para>PREFIX (all releases)</para>
        </listitem>
      </itemizedlist>

      <para>There are a number of other environmental variables that you can
      set to cause the directory to be populated for a particular target
      environment:</para>

      <itemizedlist>
        <listitem>
          <para>DEBIAN - Debian-based systems (Debian, Ubuntu, etc.)</para>
        </listitem>

        <listitem>
          <para>SUSE - SEL and OpenSuSE</para>
        </listitem>

        <listitem>
          <para>REDHAT - RHEL, CentOS, Foobar, etc.</para>
        </listitem>

        <listitem>
          <para>MAC - Apple MacIntosh (Shorewall-core, Shorewall and
          Shorewall6 packages only)</para>
        </listitem>

        <listitem>
          <para>CYGWIN - Cygwin under Windows (Shorewall-core, Shorewall and
          Shorewall6 packages only)</para>
        </listitem>

        <listitem>
          <para>OPENWRT - OpenWRT (Shorewall-core, Shorewall-lite,
          Shorewall6-lite and Shorewall-init only)</para>
        </listitem>
      </itemizedlist>

      <para>See the <ulink url="Install.htm">installation article</ulink> for
      additional information</para>
    </section>
  </section>
</article>