SA-COMPILE(1p)

📦
version 4.0.2+svn1935691 · 9 versions
, in ubuntu stonking

💖 sa-compile — compile SpamAssassin ruleset into native code 💖

okay bestie, welcome to sa-compile (section 1p of the manual, user contributed perl docs, iykyk) 🎀 she's a little compiler-gremlin for your SpamAssassin rules and she's literally so good at her job.

✨ SYNOPSIS ✨

sa-compile [options]

The options, laid out for you, no cap:

--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/spamassassin)
--updatedir=path              Directory to place updates
        (default: /var/lib/spamassassin/compiled/<perlversion>/4.000003)
--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. lowkey important: no part of user_prefs, and no files included from user_prefs, can be built into the compiled set. not a single one. that's just not her lane 🚫

that compiled set then gets used by the Mail::SpamAssassin::Plugin::Rule2XSBody plugin to speed up SpamAssassin's operation — where possible, and, crucially, when that plugin is loaded. the way that plugin changes everything 💅

re2c can match strings much faster than perl code because it constructs a DFA to match a whole bunch of simple strings in parallel and then compiles that into native object code. iconic behaviour. but heads up: not all SpamAssassin rules are amenable to this conversion, so don't come for her about the ones that aren't 🙈

this whole thing requires re2c (see https://re2c.org/) and the C compiler used to build Perl XS modules, both installed. no tools, no magic ✨

okay and this is the part everybody misses: running this and creating a compiled ruleset will have no effect on SpamAssassin scanning speeds unless you also edit your v320.pre file and make sure 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. she does her thing and dips. you gotta handle the reload yourself, bestie 😭

🦋 OPTIONS 🦋

  • --list — output the extracted base strings to STDOUT, instead of generating the C extension code. just the strings, no code-gen, show me the receipts ✨
  • --sudo — use sudo(8) to run code as 'root' when writing files to the compiled-rules storage area (which is /var/lib/spamassassin/compiled/5.040/4.000003 by default). root energy, but make it consensual 👑
  • --quiet — produce less diagnostic output. errors will still be displayed though, she's not gonna hide the drama from you.
  • --keep-tmps — keep temporary files after the script completes, instead of deleting them. hoarder mode: activated 🎀
  • -C path, --configpath=path, --config-file=path — use the specified path for locating the distributed configuration files. ignore the default directories (usually /usr/share/spamassassin or similar). you're choosing your own adventure here.
  • --siteconfigpath=path — use the specified path for locating site-specific configuration files. ignore the default directories (usually /etc/spamassassin or similar).
  • --updatedir — by default, sa-compile will use the system-wide rules update directory:
/var/lib/spamassassin/compiled/5.040/4.000003

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

note that use of this option is not recommended; 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. fr fr, don't fight the build system, fix the build system 💀
  • --cf='config line' — add 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. stack 'em up 🫶
  • -p prefs, --prefspath=prefs, --prefs-file=prefs — read user score preferences from prefs (usually $HOME/.spamassassin/user_prefs). your personal vibes file 💜
  • -D [area,...], --debug [area,...] — produce 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>. go read the lore 📚

  • -h, --help — print help message and exit.
  • -V, --version — print sa-compile version and exit.

🌈 SEE ALSO 🌈

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

the whole friend group, honestly.

🧚 PREREQUISITES 🧚

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

💀 BUGS 💀

see <https://bz.apache.org/SpamAssassin/> — it's giving bug tracker, go report it there bestie.

👑 AUTHORS 👑

the Apache SpamAssassin(tm) Project <https://spamassassin.apache.org/>

SpamAssassin is distributed under the Apache License, Version 2.0, as described in the file LICENSE included with the distribution.

Copyright (C) 2015 The Apache Software Foundation

okay that's the whole page, mwah 😘 this one's perl v5.40.1, dated 2026-07-23, and it's the sa-compile(1p) manual, so now you know everything she knows. go compile something gorgeous 🎀✨💖

📦 where this page comes from