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