Building Shorewall from SVN

Building Shorewall from SVN Tom Eastep 2009 Thomas M. Eastep 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 GNU Free Documentation License. This information is provided primarily for Shorewall developers. Users are expected to install from pre-built tarballs or packages. Beginning with Shorewall 4.4, the Shorewall project will use Git as it's SCM system rather than SVN. This document will be updated prior to the release of 4.4 to refect the move to Git.

SVN Taxonomy The Shorewall SVN tree at Sourceforge has a number of branches which are described in the following sections. It is not possible to simply export a directory from SVN and run the install.sh script in that directory. A build step is required to produce a directory that is suitable for the install.sh script to run in.

tags As new stable releases are made, they are copied into this branch. Each release has it's own directory which is named with the minor release number (e.g., 4.2.6).

branches The latest copy of each stable major release is kept in this branch. Each major release has its own directory which is named with the major release number (e.g., 4.2).

trunk The development branch of each product is kept here. Shorewall Shorewall6 Shorewall-lite Shorewall6-lite There are also several other directories which are described in the following sub-sections.

trunk/docs 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 branches.

trunk/web The files from the web site that are maintained in HTML format. are kept in this directory.

trunk/manpages, trunk/manpages6, trunk/manpages-lite and trunk/manpages6-lite The development release XML manpages. Depending on the point in the release cycle, these documents may also apply to the current stable version. In that case, there will be no corresponding directories in the release's directory in branches.

trunk/tools This is where the release and build tools are kept. There are two subordinate directories: trunk/tools/build Tools for building and uploading new releases. trunk/tools/web Tools for publishing web content.

Build Tools As described above, the build tools are kept in trunk/tools/build. They are described in the following sections.

setversion The setversion script updates the version number is a directory.

setversion version

The version may either be a minor version or a patch version. The sub-directores that are updates are those which match the specified version: Minor Version (e.g., 4.2.7) Updates Shorewall, Shorewall-common, Shorewall-perl, Shorewall-shell, Shorewall-lite, Shorewall6 and Shorewall6-lite. Only those directories that are present are updated. Patch Version (e.g., 4.2.7.1) Update those directories matching the patch version n (last digit): Shorewall-n ,Shorewall-common-n, Shorewall-shell-n, Shorewall-lite-n, Shorewall6-n, and Shorewall6-lite-n.

buildshorewall and build44 These are the scripts that build Shorewall packages from SVN. The buildshorewall script builds Shorewall 4.0 and Shorewall 4.2 packages; the build44 script builds Shorewall 4.3 and 4.4 packages. Because the scripts work similarly, they will be described together. The build scripts copy content from SVN using the svn export command. They then use that content to build the packages. In addition to the usual Gnu utilities, the following software is required: rpmbuild (I use rpm version 4.4.2.3-20.3) Required to build the RPM packages. xsltproc (libxslt -- I use version 1.1.24-19.1) Required to convert the XML documents to other formats. Docbook XSL Stylesheets (I use docbook-xsl-stylesheets version 1.74.0-1.35) Required to convert the XML documents to other formats. Perl (I use Perl 5.10.0-62.17.1) Required to massage some of the config files. xmlto (I use version 0.0.18-182.27) Required to convert the XML manpages to manpages. You should ensure that you have the latest script. The scripts change periodically as we move through the release cycles. 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: STYLESHEET Must point to the XHTML docbook.xsl stylesheet from your Docbook XSL Stylesheets installation. LOGDIR Directory where you want the build log placed. Defaults to the current working directory. RPMDIR Points to your RPM directory . DIR Directory where you want the release to be built. Defaults to the current working directory. GPG Command to be used for signing your packages SVN Shorewall SVN repository The scripts assume that there will be a separete build directory per major release. To build a release, you cd to the appropriate directory and run the build script. The general form of the build command is:

buildscript [ -options ] release [ prior release ]

where buildscript is either buildshorewall or build44 options are one of the following. If no options are given then all options are assumed t build tar files r build RPMs S sign the packages using GnuPg c Build the common package (shorewall-common on versions 4.0 and 4.2 and shorewall on 4.3 and later) l Build the shorewall-lite package. 6 Build the shorewall6 package. L Build the shorewall6-lite package. p Build the shorewall-perl package (versions 4.0 and 4.2 only) s Build the shorewall-shell package (versions 4.0 and 4.2 only) release The release version to build. Must match the version in the associated SVN path. prior release The release to be used to generate patch files. Example 1 - Build Shorewall 4.2.7 and generate patches against 4.2.6:

buildshorewall 4.2.7 4.2.6

Example 2 - Build Shorewall 4.2.7.1 Shorewall-perl and generate patches against 4.2.7:

buildshorewall -trSp 4.2.7.1 4.2.7

upload 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.

upload [ -products ] release

where products specifes the products to upload. If not given, all products are uploaded. This option is generally given only when uploading a patch release. c Upload the common package (shorewall-common on versions 4.0 and 4.2 and shorewall on 4.3 and later) l Upload the shorewall-lite package. 6 Upload the shorewall6 package. L Upload the shorewall6-lite package. p Upload the shorewall-perl package (versions 4.0 and 4.2 only) s Upload the shorewall-shell package (versions 4.0 and 4.2 only) release The version number of the release to update. Example 1 - Upload release 4.2.7:

upload 4.2.7

Example 2 - Upload shorewall-perl-4.2.7.3:

upload -p 4.2.7.3

Patch Releases Patch releases are created when a defect is found in the current stable release of one of the products and the nature of the problem warrents releasing a fix before the next minor release. The basic steps in creating a patch release n are as follows: Create tags/minor-version/Shorewall-common-n or Shorewall-n depending on which release. If that product is being changed, the svn cp command can be used. Otherwise, use svn mkdir and then svn cp the changelog.txt and releasenotes.txt files from the last release (either the minor release itself or the preceding patch release. For each of the other products, create a product-n directory (e.g., Shorewall-perl-n) using svn cp. Again the last released version of the minor version of the product should be the source. Apply the changes necessary to fix the bug, including updating the change log and release notes. Run setversion to set the version of the updated product(s). Create tags/minor-version/known_problems.txt if it doesn already exist and add a description of the defect and indicate the patch release in which it was corrected. Commit the fix to SVN. Build the product(s).