shorewall_code/docs/Build.xml

546 lines
15 KiB
XML
Raw Permalink Normal View History

<?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>
<listitem>
<para>Shorewall-init</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 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>trunk/manpages, trunk/manpages6, trunk/manpages-lite and
trunk/manpages6-lite</title>
<para>The stable release XML manpages. Depending on the point in the
release cycle, these documents may also apply to the current
development version.</para>
</section>
</section>
<section>
<title>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>
<title>web</title>
<para>The files from the web site that are maintained in HTML format.
are kept in this directory.</para>
</section>
<section>
<title>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 it's own Git repository.</para>
</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
2009-05-30 17:34:34 +02:00
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>build</title>
<para>This is the script that builds Shorewall 4.4 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</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.23.</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 build44 script 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. 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>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 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>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>build 4.3.7 4.3.6</command></para>
</blockquote>
2009-05-30 17:34:34 +02:00
<para>Example 2 - Build Shorewall 4.2.7.1 Shorewall and generate patches
against 4.2.7:</para>
<blockquote>
<para><command>build -trc 4.3.7.1 4.3.7</command></para>
</blockquote>
</section>
<section>
<title>upload</title>
<para>This script is used to upload a release to www1.shorewall.net. 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>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>i</term>
<listitem>
<para>Upload the shorewall-init 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-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 and Shorewall6 packages
only)</para>
</listitem>
<listitem>
<para>CYGWIN - Cygwin under Windows (Shorewall and Shorewall6
packages only)</para>
</listitem>
</itemizedlist>
</section>
</section>
</article>