SA-COMPILE(1)

📦
version 4.0.2 · 10 versions
, in alpine 3.23

💅 SA-COMPILE(1) — the sa-compile page, but make it make sense

okay so real talk bestie, this is one of those Perl-doc manual pages (you know, the "User Contributed Perl Documentation" kind), and it's about sa-compile. grab a snack, it's actually kind of a slay 🍓

✨ NAME ✨

sa-compile — compile the SpamAssassin ruleset into native code. yes, like, actually native. it's giving compiler-girl Summer 💅

🌸 SYNOPSIS 🌸

sa-compile [options]

Options:

  • --list — Output base string list to STDOUT
  • --sudo — Use 'sudo' for privilege escalation
  • --keep-tmps — Keep temporary files instead of deleting
  • -C path, --configpath=path, --config-file=path — Path to standard configuration dir
  • -p prefs, --prefspath=file, --prefs-file=file — Set user preferences file
  • --siteconfigpath=path — Path for site configs (default: /usr/etc/mail/spamassassin)
  • --updatedir=path — Directory to place updates (default: /var/lib/spamassassin/compiled/<perlversion>/4.000002)
  • --cf='config line' — Additional line of configuration
  • -D, --debug [area=n,...] — Print debugging messages
  • -V, --version — Print version
  • -h, --help — Print usage message

💖 DESCRIPTION 💖

so sa-compile uses re2c to compile the site-wide parts of the SpamAssassin ruleset. and no cap: no part of user_prefs or any files included from user_prefs can be built into the compiled set. that's just how it is, bestie 🫶

this compiled set is then used by the Mail::SpamAssassin::Plugin::Rule2XSBody plugin to speed up SpamAssassin's operation, where possible, and when that plugin is loaded. iykyk.

the way re2c works is lowkey iconic — it can match strings much faster than perl code, by constructing a DFA to match many simple strings in parallel, and compiling that to native object code. 🔥 but — and this is the important part — not all SpamAssassin rules are amenable to this conversion, however. some rules just don't vibe with it, periodt.

this whole thing requires re2c (see https://re2c.org/), plus the C compiler used to build Perl XS modules, be installed. both of them. no skipping 🙈

note that running this, and creating a compiled ruleset, will have no effect on SpamAssassin scanning speeds unless you also edit your v320.pre file and ensure this line is uncommented:
loadplugin Mail::SpamAssassin::Plugin::Rule2XSBody

additionally, sa-compile will not restart spamd or otherwise cause a scanner to reload the now-compiled ruleset automatically. it's not gonna do it for you, girl, you gotta do it yourself 😭

🎀 OPTIONS 🎀

  • --list — outputs the extracted base strings to STDOUT, instead of generating the C extension code. like a little preview, cute.
  • --sudo — uses sudo(8) to run code as 'root' when writing files to the compiled-rules storage area (which is /var/lib/spamassassin/compiled/5.042/4.000002 by default). main character energy, honestly 👑
  • --quiet — produces less diagnostic output. but bestie, errors will still be displayed. we're quiet, not blind 💀
  • --keep-tmps — keeps temporary files after the script completes, instead of deleting them. hoarder behavior but make it unix 🎀
  • -C path, --configpath=path, --config-file=path — uses the specified path for locating the distributed configuration files. this makes it ignore the default directories (usually /usr/share/spamassassin or similar). bye default dirs 👋
  • --siteconfigpath=path — uses the specified path for locating site-specific configuration files. this ignores the default directories (usually /etc/mail/spamassassin or similar).
  • --updatedir — by default, sa-compile will use the system-wide rules update directory:
/var/lib/spamassassin/compiled/5.042/4.000002

if the updates should be stored in another location, specify it here.

note that use of this option is not recommended. fr fr, if sa-compile is placing the compiled rules in the wrong directory, you probably need to rebuild SpamAssassin with different Makefile.PL arguments instead of overriding sa-compile's runtime behaviour. don't fight the build system, bestie, just rebuild it 💅
  • --cf='config line' — adds additional lines of configuration directly from the command-line, parsed after the configuration files are read. multiple --cf arguments can be used, and each will be considered a separate line of configuration. stacking them like friendship bracelets 🦋
  • -p prefs, --prefspath=prefs, --prefs-file=prefs — reads user score preferences from prefs (usually $HOME/.spamassassin/user_prefs). it's the home-girl path 🏠
  • -D [area,...], --debug [area,...] — produces debugging output. if no areas are listed, all debugging information is printed. diagnostic output can also be enabled for each area individually; area is the area of the code to instrument.

for more information about which areas (also known as channels) are available, please see the documentation at https://wiki.apache.org/spamassassin/DebugChannels. the lore is all there 📚

  • -h, --help — prints the help message and exits. bless.
  • -V, --version — prints the sa-compile version and exits. 🎀

🌈 SEE ALSO 🌈

Mail::SpamAssassin(3) spamassassin(1) spamd(1)

🧚 PREREQUISITES 🧚

Mail::SpamAssassin re2c Mail::SpamAssassin::Plugin::Rule2XSBody

🙈 BUGS 🙈

see https://bz.apache.org/SpamAssassin/ — it's giving issue-tracker realness 🔥

👑 AUTHORS 👑

The Apache SpamAssassin(tm) Project <https://spamassassin.apache.org/> — absolute icons, no notes.

SpamAssassin is distributed under the Apache License, Version 2.0, as described in the file LICENSE included with the distribution. read it, it's good for you 🫶

Copyright (C) 2015 The Apache Software Foundation

so yeah, that's the whole vibe check 💜 — this page lives in the User Contributed Perl Documentation section (perl v5.42.0, dated 2025-08-31), and honestly? iconic of it. mwah 💋✨

📦 where this page comes from