PACKAGING

Introduction
------------

The Makefile which is used to build SpamAssassin is created by calling
	perl Makefile.PL

This is the standard Perl way of building packages. It involves the
Perl module ExtUtils::MakeMaker which creates a Makefile.

ExtUtils::MakeMaker recognizes several variables which can be set at
the command line to give the user the possibility to influence the
contents of the generated Makefile. All macros written to the Makefile
can be changed on the command line like this:
	perl Makefile.PL FOO="bar"
This would give the (exemplary) macro 'FOO' the value 'bar'.

Now has the internal structure of ExtUtils::MakeMaker and that of the
generated Makefiles changed over the years. For a description of the
features your version supports, please read
	perldoc ExtUtils::MakeMaker

One important thing to know when you're building packages is that Perl
uses three different "repositories" for installed modules and their
corresponding files: 'perl', 'site' and 'vendor' (the latter was
introduced with Perl 5.6.0). These have the following meanings:

  perl:   This should be used only by essential modules shipped with
          Perl or modules required by one of these. And maybe for some
          other important modules chosen by some obscure selection
          process. Only one thing is sure about this set of directories:
          SpamAssassin doesn't belong there.

  site:   This is the default. The libs (.pm files) of the modules are
          installed into the site_perl subdir in the Perl lib dir.
          Everything installed via the CPAN shell or directly from
          sources should go there.

  vendor: This repository was officially introduced some time after
          Perl 5.005_03 (maybe with 5.6.0). It's intended to be the
          target for all modules installed from distribution specific
          packages; that means RPMs, debs, ebuilds, etc. The rationale
          behind this is that this prevents modules installed by the
          user from being overwritten by packaged ones.

The wanted repository can be chosen by setting the variable INSTALLDIRS.
So according to the description above should packages probably use
	perl Makefile.PL INSTALLDIRS=vendor
That's definitely the correct way to go for Debian, according to their
Perl Policy [DEBPERL]. But I've heard that the vendor stuff is either
broken or not set on many other systems, especially Red Hat ones. Google
might help to find out more on this topic.

The following resources might help understanding this stuff:
[MANEUMM616], [MM00779], [P5P94113].


Changing paths in the Makefile
------------------------------

Internally the Makefile defined quite some paths for the different settings
of INSTALLDIRS. One can change them directly but to be independent of the
version of ExtUtils::MakeMaker the following variables should be used:

PREFIX:
  Sets the prefix below which SpamAssassin is installed. Please note the
  exceptions for SYSCONFDIR.

  Default is the prefix Perl was built with (call
  	perl -V:prefix
  to see the value). Normally something like /usr or /usr/local.

  Samples:
    This will install the spamassassin apps in /foo/bin, the libs in
    /foo/lib/perl5, the shared stuff in /foo/share/spamassassin and make
    SpamAssassin look for config files in /foo/etc/mail/spamassassin:
    	perl Makefile.PL PREFIX=/foo

LIB:
  This will change the directory where the SpamAssassin libraries (.pm files)
  are installed. The module's architecture-independent files will be put into
  the given directory, the architecture-dependent files into a subdirectory
  with the name of the current architecture.

  The default is something like PREFIX/lib/perl5/site_perl/PERL_VERSION (for
  INSTALLDIRS=site).

  Samples:
    Under i686-Linux, put the architecture-independent files below ~/.libs
    and the architecture-dependent ones below ~/.libs/i686-linux:
    	perl Makefile.PL LIB=~/.libs

DATADIR (DEFRULESDIR):
  SpamAssassin's real logic lies in its shipped rule definitions and the
  corresponding scores. The files with these settings have to be saved
  somewhere, normally below PREFIX/share/spamassassin. The full path to
  that directory can be changed with this variable (DEFRULESDIR is a
  synonym).

  ATTENTION: All files within this directory are removed when SpamAssassin
  is installed!

  Samples:
    Install everything into the default locations but put the rules in
    /tmp/sa-rules (for whatever reason):
    	perl Makefile.PL DATADIR=/tmp/sa-rules


SYSCONFDIR:
  Sets the base dir for the config files. See also CONFDIR.

  The default depends on the PREFIX and is compliant to the FHS:
    - if PREFIX is either /usr or /usr/local:
      /etc
    - if PREFIX starts with /opt:
      /etc/opt
    - else:
      PREFIX/etc

  Samples:
    This will (on Windows) install below 'C:\Program Files\SpamAssassin' but
    look for the config files in 'C:\Program Files\Shared Files\SpamAssassin':
    	perl Makefile.PL PREFIX="C:/Program Files/SpamAssassin"
    	  SYSCONFDIR="C:/Program Files/Shared Files/SpamAssassin"

    To put the apps and libs below ~/.sa-bin but the config below ~/.sa-etc
    try the following:
    	perl Makefile.PL PREFIX=$HOME/.sa-bin SYSCONFDIR=$HOME/.sa-etc

    And the following installs SpamAssassin in /usr/local and forces the
    config files to be below /usr/local, too:
    	perl Makefile.PL PREFIX=/usr/local SYSCONFDIR=/usr/local/etc

CONFDIR (LOCALRULESDIR):
  SpamAssassin looks for its config files in SYSCONFDIR/mail/spamassassin.
  (There is also a sample local.cf created if such a file doesn't exist yet.)
  Some people didn't like this path for various reasons so the full path to
  the config files can be changed here (this more or less makes SYSCONFDIR
  obsolete). A synonym for this variable is LOCALRULESDIR.

  Samples:
    If you'd like to have the config files directly in /etc/spamassassin
    try this:
    	perl Makefile.PL CONFDIR=/etc/spamassassin

LOCALSTATEDIR:
  "sa-update" will download rule updates into LOCALSTATEDIR/spamassassin.

  The default depends on the PREFIX and is compliant to the FHS:
    - if PREFIX is either /usr or /usr/local:
      /var/lib
    - if PREFIX starts with /opt:
      /var/opt
    - else:
      PREFIX/var

  Samples:
    If you'd like to have the downloaded rules files in /var/spamassassin
    try this:
    	perl Makefile.PL LOCALSTATEDIR=/var


Installing to a directory different from the final destination
--------------------------------------------------------------

When you're building packages, it's often needed to install the stuff to
some temporary directory and then build the package from there. The problem
with this approach is that the build system of SpamAssassin needs to write
some final paths to the libs and the applications.

Previous versions offered some complicated variables to achieve this. Those
hacks weren't compatible to current versions of ExtUtils::MakeMaker. But
ExtUtils::MakeMaker 6.06 introduced a feature which is well known from the GNU
build tools [GNUMAKECMD]: The variable DESTDIR.

The value of DESTDIR is simply prepended to all other paths on make install.
So if you wanted to create a SpamAssassin package for a system which will
have it installed in /usr but you want to create that package from some temp
dir, you would do something like this:
	perl Makefile.PL Makefile.PL PREFIX=/usr DESTDIR=/tmp/sa-build
	make
	make disttest
	make install
	cd /tmp/sa-build
	build_some_package


Setting further options on the command line
-------------------------------------------

Besides the directories, the build process of SpamAssassin supports several
other settings to set or enable some features. For some of these settings
the user is asked before the Makefile is created. To avoid these questions
(and accept the defaults, whatever they are) it is possible to redirect
STDIN from the null device like this:
	perl Makefile.PL < /dev/null
Or, under Windows:
	perl Makefile.PL < nul

The following variables are supported:

ENABLE_SSL:
  Can be set to either "yes" or "no" (default). Makes it possible to use SSL
  encryption on the (TCP) connection between spamc and spamd.

  Sample:
    Build spamc with SSL, use defaults for all other questions:
    	perl Makefile.PL ENABLE_SSL=yes < /dev/null

CONTACT_ADDRESS:
  Each reported spam contains an address under which the confused user/client
  can request more information about the tagging of his mail. That address can
  be set here. The default is to query the buildung user, falling back to the
  string "the administrator of that system".

  Sample:
    The user can find some information on the page http://example.com/tag/:
    	perl Makefile.PL CONTACT_ADDRESS="http://example.com/tag/"

RUN_NET_TESTS:
  Vipul's Razor and Net::DNS are optional modules. If one of those modules is
  found to be installed, some special tests can be performed when 'make test'
  is run. The builder is asked if he wants to do so. Default is "no" (because
  those tests can fail if there are problems with the network connection or
  the servers).

  Sample:
    Run only the Razor tests:
	perl Makefile.PL RUN_NET_TESTS=yes < /dev/null
	make test TEST_FILES="t/razor*.t"


Twisting Perl details
---------------------

The build process of SpamAssassin has to know several details of the Perl
calling it later. This is used to work around some Perl bugs and make it
all actually work :o) The following additional variables are supported to
modify these settings:

PERL_BIN:
  The path to the perl application which will be used to call the scripts
  (like spamassassin and spamd). It makes sense to set this if you build
  SpamAssassin on some weird build host which happen to have Perl in
  /some/weird/location which is definitely not the location on the end
  user's box. The default is the value of the macro FULLPERL which should
  be the path to the perl processing Makefile.PL.

  Sample:
    Building with some weird perl:
    	/local/buildsys/perl-5.6.1/bin/perl Makefile.PL PERL_BIN=/usr/bin/perl


Obsolete Variables
------------------

The following list shows variables recognized by the old build system and
their new counterparts (no, the ones in the end aren't in the wrong order,
it actually was that complicated):

old: PREFIX=/bar/foo INST_PREFIX=/foo
new: PREFIX=/foo     DESTDIR=/bar

old: INST_SITELIB=/foo
new: LIB=/foo

old: SYSCONFDIR=/bar/foo INST_SYSCONFDIR=/foo
new: SYSCONFDIR=/foo     DESTDIR=/bar

old: LOCAL_RULES_DIR=/foo PKG_LOCAL_RULES_DIR=/bar/foo
new: LOCALRULESDIR=/foo   DESTDIR=/bar

old: DEF_RULES_DIR=/foo   PKG_DEF_RULES_DIR=/bar/foo
new: DEFRULESDIR=/foo     DESTDIR=/bar

Using one of the following variables will make the Makefile generation
process die:
  INST_PREFIX
  INST_SITELIB
  INST_SYSCONFDIR
  LOCAL_RULES_DIR
  DEF_RULES_DIR

If you think you need to use one of those nevertheless, you can set the
variable IGNORE_CRUFT to "yes".


Resources
---------

[BUGZILLA] SpamAssassin bug database:
  <http://issues.apache.org/SpamAssassin/>

[DEBPERL] Debian Perl Policy, Chapter 3: Packaged Modules:
  <http://www.debian.org/doc/packaging-manuals/perl-policy/ch-module_packages.html>

[GNUMAKECMD] GNU make manual: Make Conventions: Variables for Specifying
  Commands
  <http://www.gnu.org/manual/make-3.79.1/html_chapter/make_14.html#SEC119>

[MANEUMM616] The man page for ExtUtils::MakeMaker 6.16:
  <http://search.cpan.org/author/MSCHWERN/ExtUtils-MakeMaker-6.16/lib/ExtUtils/MakeMaker.pm#Default_Makefile_Behaviour>

[MM00779] makemaker-at-perl-dot-org: Michael G Schwern: "Re: MakeMaker
  problems with relocation" (PREFIX was broken):
  <http://www.mail-archive.com/makemaker@perl.org/msg00779.html>

[P5P94113] perl5-porters: Michael G Schwern: "Re: OS X's vendorlib default
  seems wrong" (description of different repositoreis):
  <http://archive.develooper.com/perl5-porters@perl.org/msg94113.html>

[RHBUG78053] Red Hat bug 78053: "incompatible changes in behavior of
  MakeMaker; affects rpm build process" (introduction of DESTDIR):
  <https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=78053>