Krang Build System Design

The Krang build system is responsible for compiling Krang from source into a form suitable for distribution and installation. This document describes the design of the build system.

Background

Krang's first releases included binaries built for Redhat 7.3 on the i686 platform. Binaries for all CPAN XS modules as well as Apache/mod_perl are included in the distribution tar-ball. The installation system (krang_install) simply copies these binaries into place, sets up the database and configures Krang using information provided by the user. This system works very well, provided you're running Redhat 7.3 or a compatible system.

The goal of the build system is to produce pre-compiled packages for a variety of platforms which will be installable via krang_install the same way the original Redhat 7.3 package works. After this work is complete future development may produce native packages (RPM, DEB, etc.) as an alternative to krang_install.

Krang currently includes facilities for installing Perl and MySQL which will not be provided by the build system envisioned here. This system will expect the target environment to include suitable versions of Perl and MySQL prior to installation.

Design Considerations

The following factors are important to the success of the build system.

Perl

Each distribution must target a particular version of Perl. This is necessary for the correct operation of both compiled XS modules and Apache/mod_perl.

System Libraries

Each distribution will require certain system libraries, such as Expat and libdb.

MySQL

Krang depends on MySQL but does not include MySQL in its distribution.

Build Automation

It must be very easy to build a distribution for a supported platform.

Build Testing

Automated testing against all supported platforms will be useful in preventing broken releases. (perl5-porters uses tinderbox for this, I think)

Code Duplication

Although each platform will have certain peculiarities, much of the process will be the same. This is particular true for various versions of a platform (Redhat 7.3, Redhat 8 and Redhat 9 for example).

Install-Time Activities

Aside from building binaries, some install-time activities vary between platforms. For example, the original distribution sets up Krang to start when the system boots by putting a link to krang_ctl in /etc/init.d. This may not be correct for all platforms.

Architecture

Naming Conventions

Krang distributions are created to work on a specific platform with a specific version of Perl. For example, typical distribution filenames might be:

  krang-1.101-Redhat7.3-perl5.6.1-i686-linux.tar.gz
  krang-1.101-Redhat9-perl5.8.2-i686-linux.tar.gz

The build system will supply the distribution name (Redhat9, Redhat7.3, etc) and Perl will provide the Perl version and architecture using:

  perl -MConfig -e 'printf "perl%d.%d.%d-%s",
                    (map { ord($_) } split("", $^V, 3)), $Config{archname}'

End-users must choose the distribution that matches their platform, although krang_install will check to make sure they made the right reasonable choice.

A special source distribution is made without building platform binaries. Users of this distribution will need to use the Krang build system to produce a distribution they can install. The source distribution will be named:

  krang-1.101-src.tar.gz

Platform Files

Each supported platform must have a directory in the platforms/ directory inside Krang. This directory will contain at least one module, Platform.pm, which is a sub-classes of Krang::Platform. This module may actually be a sub-class of another platform's module: ex. the platform module for Redhat9 could be based on the module for Redhat7.3.

A README file may also be present which will be copied as ``README.$Platform'' into compiled distributions.

Implementation

krang_build

To generate a build for a platform, the krang_build script will be run with a single argument:

  krang_build Redhat7.3

This will cause the build system to use the Platform.pm module in platform/Redhat7.3. If all goes well the final line of output should be something like:

   Build finished, created krang-1.101-Redhat7.3-perl5.6.1-i686-linux.tar.gz

The build a distribution using a different version Perl, just run krang_build using the desired perl:

   perl5.8.3 krang_build Redhat7.3

In general, building a distribution for a platform will only work on the platform itself. Automation using VMWare and Tinderbox may reduce the work associated with building and testing on each platform.

Krang::Platform

The Krang::Platform module will serve as a base-class for all platform modules. The following methods will be available for overriding in sub-classes. See the module documentation in Krang::Platform for authoritative details.

• verify_dependencies()
  
Makes sure all required dependencies are in place before starting the build, and before beginning installation. Krang::Platform will provide a way to know whether the system is being built or installed.
• build_perl_module($src)
  
Called to build a specific Perl module from the '$src' file. The default implementation will simply use make install, but platforms can override this to provide special processing for difficult modules.
• build_apache()
  
Called to build Apache. The default implementation will work the way the current Makefile in src/Apache-MOD_PERL works.
• apache_build_parameters()
  
Override to modify the parameters passed to Apache's configure script. This should provide an easy way to fix Apache compilation on most platforms.
• build_modperl()
  
Called to build Apache. The default implementation will work the way the current Makefile in src/Apache-MOD_PERL works.
• modperl_build_parameters()
  
Override to modify the parameters passed to mod_perl's Makefile.PL script. This should provide an easy way to fix mod_perl compilation on most platforms.
• finish_installation()
  
Anything that needs to be done at the end of installation can be done here. This is where the Redhat modules would add a link in /etc/init.d, for example.
• finish_upgrade()
  
Anything that needs to be done at the end of an upgrade can be done here.

Questions

Do we need a platform.conf? This would be a configuration file created during build (and possibly modified during installation) collecting information about the platform. Could be used at run-time to find binaries like mysql, tar, etc.
Are there methods missing from the Krang::Platform section that we'll probably need?
Which platforms should we target for the first release? Redhat 7.3 and 9 are easy to do at PIRT. It sounds like Perrin is up for handling Fedora. I think we should choose something exotic so we don't end up leaving Redhat-specific stuff in place. Maybe FreeBSD? Eventually something non-x86 would be good, maybe Mac OSX or Solaris.
What changes will be needed to krang_makedist?