upstream/PACKAGING

   1
   2 Introduction
   3 ------------
   4
   5 The Makefile which is used to build SpamAssassin is created by calling
   6         perl Makefile.PL
   7
   8 This is the standard Perl way of building packages. It involves the
   9 Perl module ExtUtils::MakeMaker which creates a Makefile.
  10
  11 ExtUtils::MakeMaker recognizes several variables which can be set at
  12 the command line to give the user the possibility to influence the
  13 contents of the generated Makefile. All macros written to the Makefile
  14 can be changed on the command line like this:
  15         perl Makefile.PL FOO="bar"
  16 This would give the (exemplary) macro 'FOO' the value 'bar'.
  17
  18 Now has the internal structure of ExtUtils::MakeMaker and that of the
  19 generated Makefiles changed over the years. For a description of the
  20 features your version supports, please read
  21         perldoc ExtUtils::MakeMaker
  22
  23 One important thing to know when you're building packages is that Perl
  24 uses three different "repositories" for installed modules and their
  25 corresponding files: 'perl', 'site' and 'vendor' (the latter was
  26 introduced with Perl 5.6.0). These have the following meanings:
  27
  28   perl:   This should be used only by essential modules shipped with
  29           Perl or modules required by one of these. And maybe for some
  30           other important modules chosen by some obscure selection
  31           process. Only one thing is sure about this set of directories:
  32           SpamAssassin doesn't belong there.
  33
  34   site:   This is the default. The libs (.pm files) of the modules are
  35           installed into the site_perl subdir in the Perl lib dir.
  36           Everything installed via the CPAN shell or directly from
  37           sources should go there.
  38
  39   vendor: This repository was officially introduced some time after
  40           Perl 5.005_03 (maybe with 5.6.0). It's intended to be the
  41           target for all modules installed from distribution specific
  42           packages; that means RPMs, debs, ebuilds, etc. The rationale
  43           behind this is that this prevents modules installed by the
  44           user from being overwritten by packaged ones.
  45
  46 The wanted repository can be chosen by setting the variable INSTALLDIRS.
  47 So according to the description above should packages probably use
  48         perl Makefile.PL INSTALLDIRS=vendor
  49 That's definitely the correct way to go for Debian, according to their
  50 Perl Policy [DEBPERL]. But I've heard that the vendor stuff is either
  51 broken or not set on many other systems, especially Red Hat ones. Google
  52 might help to find out more on this topic.
  53
  54 The following resources might help understanding this stuff:
  55 [MANEUMM616], [MM00779], [P5P94113].
  56
  57
  58 Changing paths in the Makefile
  59 ------------------------------
  60
  61 Internally the Makefile defined quite some paths for the different settings
  62 of INSTALLDIRS. One can change them directly but to be independent of the
  63 version of ExtUtils::MakeMaker the following variables should be used:
  64
  65 PREFIX:
  66   Sets the prefix below which SpamAssassin is installed. Please note the
  67   exceptions for SYSCONFDIR.
  68
  69   Default is the prefix Perl was built with (call
  70         perl -V:prefix
  71   to see the value). Normally something like /usr or /usr/local.
  72
  73   Samples:
  74     This will install the spamassassin apps in /foo/bin, the libs in
  75     /foo/lib/perl5, the shared stuff in /foo/share/spamassassin and make
  76     SpamAssassin look for config files in /foo/etc/mail/spamassassin:
  77         perl Makefile.PL PREFIX=/foo
  78
  79 LIB:
  80   This will change the directory where the SpamAssassin libraries (.pm files)
  81   are installed. The module's architecture-independent files will be put into
  82   the given directory, the architecture-dependent files into a subdirectory
  83   with the name of the current architecture.
  84
  85   The default is something like PREFIX/lib/perl5/site_perl/PERL_VERSION (for
  86   INSTALLDIRS=site).
  87
  88   Samples:
  89     Under i686-Linux, put the architecture-independent files below ~/.libs
  90     and the architecture-dependent ones below ~/.libs/i686-linux:
  91         perl Makefile.PL LIB=~/.libs
  92
  93 DATADIR (DEFRULESDIR):
  94   SpamAssassin's real logic lies in its shipped rule definitions and the
  95   corresponding scores. The files with these settings have to be saved
  96   somewhere, normally below PREFIX/share/spamassassin. The full path to
  97   that directory can be changed with this variable (DEFRULESDIR is a
  98   synonym).
  99
 100   ATTENTION: All files within this directory are removed when SpamAssassin
 101   is installed!
 102
 103   Samples:
 104     Install everything into the default locations but put the rules in
 105     /tmp/sa-rules (for whatever reason):
 106         perl Makefile.PL DATADIR=/tmp/sa-rules
 107
 108
 109 SYSCONFDIR:
 110   Sets the base dir for the config files. See also CONFDIR.
 111
 112   The default depends on the PREFIX and is compliant to the FHS:
 113     - if PREFIX is either /usr or /usr/local:
 114       /etc
 115     - if PREFIX starts with /opt:
 116       /etc/opt
 117     - else:
 118       PREFIX/etc
 119
 120   Samples:
 121     This will (on Windows) install below 'C:\Program Files\SpamAssassin' but
 122     look for the config files in 'C:\Program Files\Shared Files\SpamAssassin':
 123         perl Makefile.PL PREFIX="C:/Program Files/SpamAssassin"
 124           SYSCONFDIR="C:/Program Files/Shared Files/SpamAssassin"
 125
 126     To put the apps and libs below ~/.sa-bin but the config below ~/.sa-etc
 127     try the following:
 128         perl Makefile.PL PREFIX=$HOME/.sa-bin SYSCONFDIR=$HOME/.sa-etc
 129
 130     And the following installs SpamAssassin in /usr/local and forces the
 131     config files to be below /usr/local, too:
 132         perl Makefile.PL PREFIX=/usr/local SYSCONFDIR=/usr/local/etc
 133
 134 CONFDIR (LOCALRULESDIR):
 135   SpamAssassin looks for its config files in SYSCONFDIR/mail/spamassassin.
 136   (There is also a sample local.cf created if such a file doesn't exist yet.)
 137   Some people didn't like this path for various reasons so the full path to
 138   the config files can be changed here (this more or less makes SYSCONFDIR
 139   obsolete). A synonym for this variable is LOCALRULESDIR.
 140
 141   Samples:
 142     If you'd like to have the config files directly in /etc/spamassassin
 143     try this:
 144         perl Makefile.PL CONFDIR=/etc/spamassassin
 145
 146 LOCALSTATEDIR:
 147   "sa-update" will download rule updates into LOCALSTATEDIR/spamassassin.
 148
 149   The default depends on the PREFIX and is compliant to the FHS:
 150     - if PREFIX is either /usr or /usr/local:
 151       /var/lib
 152     - if PREFIX starts with /opt:
 153       /var/opt
 154     - else:
 155       PREFIX/var
 156
 157   Samples:
 158     If you'd like to have the downloaded rules files in /var/spamassassin
 159     try this:
 160         perl Makefile.PL LOCALSTATEDIR=/var
 161
 162
 163 Installing to a directory different from the final destination
 164 --------------------------------------------------------------
 165
 166 When you're building packages, it's often needed to install the stuff to
 167 some temporary directory and then build the package from there. The problem
 168 with this approach is that the build system of SpamAssassin needs to write
 169 some final paths to the libs and the applications.
 170
 171 Previous versions offered some complicated variables to achieve this. Those
 172 hacks weren't compatible to current versions of ExtUtils::MakeMaker. But
 173 ExtUtils::MakeMaker 6.06 introduced a feature which is well known from the GNU
 174 build tools [GNUMAKECMD]: The variable DESTDIR.
 175
 176 The value of DESTDIR is simply prepended to all other paths on make install.
 177 So if you wanted to create a SpamAssassin package for a system which will
 178 have it installed in /usr but you want to create that package from some temp
 179 dir, you would do something like this:
 180         perl Makefile.PL Makefile.PL PREFIX=/usr DESTDIR=/tmp/sa-build
 181         make
 182         make disttest
 183         make install
 184         cd /tmp/sa-build
 185         build_some_package
 186
 187
 188 Setting further options on the command line
 189 -------------------------------------------
 190
 191 Besides the directories, the build process of SpamAssassin supports several
 192 other settings to set or enable some features. For some of these settings
 193 the user is asked before the Makefile is created. To avoid these questions
 194 (and accept the defaults, whatever they are) it is possible to redirect
 195 STDIN from the null device like this:
 196         perl Makefile.PL < /dev/null
 197 Or, under Windows:
 198         perl Makefile.PL < nul
 199
 200 The following variables are supported:
 201
 202 ENABLE_SSL:
 203   Can be set to either "yes" or "no" (default). Makes it possible to use SSL
 204   encryption on the (TCP) connection between spamc and spamd.
 205
 206   Sample:
 207     Build spamc with SSL, use defaults for all other questions:
 208         perl Makefile.PL ENABLE_SSL=yes < /dev/null
 209
 210 CONTACT_ADDRESS:
 211   Each reported spam contains an address under which the confused user/client
 212   can request more information about the tagging of his mail. That address can
 213   be set here. The default is to query the buildung user, falling back to the
 214   string "the administrator of that system".
 215
 216   Sample:
 217     The user can find some information on the page http://example.com/tag/:
 218         perl Makefile.PL CONTACT_ADDRESS="http://example.com/tag/"
 219
 220 RUN_NET_TESTS:
 221   Vipul's Razor and Net::DNS are optional modules. If one of those modules is
 222   found to be installed, some special tests can be performed when 'make test'
 223   is run. The builder is asked if he wants to do so. Default is "no" (because
 224   those tests can fail if there are problems with the network connection or
 225   the servers).
 226
 227   Sample:
 228     Run only the Razor tests:
 229         perl Makefile.PL RUN_NET_TESTS=yes < /dev/null
 230         make test TEST_FILES="t/razor*.t"
 231
 232
 233 Twisting Perl details
 234 ---------------------
 235
 236 The build process of SpamAssassin has to know several details of the Perl
 237 calling it later. This is used to work around some Perl bugs and make it
 238 all actually work :o) The following additional variables are supported to
 239 modify these settings:
 240
 241 PERL_BIN:
 242   The path to the perl application which will be used to call the scripts
 243   (like spamassassin and spamd). It makes sense to set this if you build
 244   SpamAssassin on some weird build host which happen to have Perl in
 245   /some/weird/location which is definitely not the location on the end
 246   user's box. The default is the value of the macro FULLPERL which should
 247   be the path to the perl processing Makefile.PL.
 248
 249   Sample:
 250     Building with some weird perl:
 251         /local/buildsys/perl-5.6.1/bin/perl Makefile.PL PERL_BIN=/usr/bin/perl
 252
 253
 254 Obsolete Variables
 255 ------------------
 256
 257 The following list shows variables recognized by the old build system and
 258 their new counterparts (no, the ones in the end aren't in the wrong order,
 259 it actually was that complicated):
 260
 261 old: PREFIX=/bar/foo INST_PREFIX=/foo
 262 new: PREFIX=/foo     DESTDIR=/bar
 263
 264 old: INST_SITELIB=/foo
 265 new: LIB=/foo
 266
 267 old: SYSCONFDIR=/bar/foo INST_SYSCONFDIR=/foo
 268 new: SYSCONFDIR=/foo     DESTDIR=/bar
 269
 270 old: LOCAL_RULES_DIR=/foo PKG_LOCAL_RULES_DIR=/bar/foo
 271 new: LOCALRULESDIR=/foo   DESTDIR=/bar
 272
 273 old: DEF_RULES_DIR=/foo   PKG_DEF_RULES_DIR=/bar/foo
 274 new: DEFRULESDIR=/foo     DESTDIR=/bar
 275
 276 Using one of the following variables will make the Makefile generation
 277 process die:
 278   INST_PREFIX
 279   INST_SITELIB
 280   INST_SYSCONFDIR
 281   LOCAL_RULES_DIR
 282   DEF_RULES_DIR
 283
 284 If you think you need to use one of those nevertheless, you can set the
 285 variable IGNORE_CRUFT to "yes".
 286
 287
 288 Resources
 289 ---------
 290
 291 [BUGZILLA] SpamAssassin bug database:
 292   <https://issues.apache.org/SpamAssassin/>
 293
 294 [DEBPERL] Debian Perl Policy, Chapter 3: Packaged Modules:
 295   <https://www.debian.org/doc/packaging-manuals/perl-policy/ch-module_packages.html>
 296
 297 [GNUMAKECMD] GNU make manual: Make Conventions: Variables for Specifying
 298   Commands
 299   <https://www.gnu.org/software/make/manual/html_node/Command-Variables.html#Command-Variables>
 300
 301 [MANEUMM616] The man page for ExtUtils::MakeMaker 6.16:
 302   <https://search.cpan.org/author/MSCHWERN/ExtUtils-MakeMaker-6.16/lib/ExtUtils/MakeMaker.pm#Default_Makefile_Behaviour>
 303
 304 [MM00779] makemaker-at-perl-dot-org: Michael G Schwern: "Re: MakeMaker
 305   problems with relocation" (PREFIX was broken):
 306   <https://www.mail-archive.com/makemaker@perl.org/msg00779.html>
 307
 308 [P5P94113] perl5-porters: Michael G Schwern: "Re: OS X's vendorlib default
 309   seems wrong" (description of different repositoreis):
 310   <https://archive.develooper.com/perl5-porters@perl.org/msg94113.html>
 311
 312 [RHBUG78053] Red Hat bug 78053: "incompatible changes in behavior of
 313   MakeMaker; affects rpm build process" (introduction of DESTDIR):
 314   <https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=78053>
 315