1. Installation
Spicy can be installed from pre-built binaries (Linux, macOS) or with Homebrew (macOS), executed via Docker containers (Linux), or built from source (Linux, macOS, FreeBSD):
We generally aim to follow Zeek’s platform policy on which platforms to support and test.
Note
If your goal is to use Spicy with Zeek, you can skip these installation instructions. Zeek comes with Spicy support built-in by default since version 5.0. See the Zeek documentation for more.
1.1. Pre-built binaries
1.1.1. Linux
We provide pre-built Spicy binaries for a range of Linux
distributions, both for the current release version and for
development builds made from the Git main
branch.
These binary artifacts are distributed as either DEB or RPM packages for the corresponding distribution; or, in a couple cases, as TAR archives. To install the binaries, download the corresponding package and execute one of the following:
- DEB packages
# dpkg --install spicy.deb
- RPM packages
# rpm -i spicy.rpm
- TAR archives
The TAR archives need to be unpacked into
/opt/spicy
. Any previous installation must be removed first:# rm -rf /opt/spicy && mkdir /opt/spicy # tar xf spicy.tar.gz -C /opt/spicy --strip-components=1
The binaries may require installation of additional dependencies; see
the Dockerfile
for the respective platform for what’s needed.
Platform |
Release Version |
Development Version |
Dockerfile |
---|---|---|---|
Alpine 3.18 |
|||
CentOS Stream 9 |
|||
Debian 11 |
|||
Debian 12 |
|||
Fedora 40 |
|||
Fedora 41 |
|||
Ubuntu 20 |
|||
Ubuntu 22 |
1.1.2. macOS
1.1.2.1. Homebrew
We provide a Homebrew formula for installation of Spicy. After installing Homebrew add the Zeek tap:
# brew tap zeek/zeek
To install the most recent Spicy release version, execute:
# brew install spicy
To instead install the current development version, execute:
# brew install --HEAD spicy
1.1.2.2. Pre-built binaries
We provide TAR archives with pre-built binaries for the following macOS versions:
macOS |
Release Version |
Development Version |
---|---|---|
Monterey (12) |
||
Ventura (13) |
The TAR archives need to be unpacked into /opt/spicy
. Any previous
installation must be removed first. To prevent macOS from quarantining
the files, you should download and unpack via the command line:
# curl -L <link-per-above> -o spicy.tar.gz
# rm -rf /opt/spicy && mkdir /opt/spicy
# tar xf spicy.tar.gz -C /opt/spicy --strip-components 1
For JIT support, these binaries require an Xcode installation.
1.2. Using Docker
The Zeek Docker images include Spicy. See their documentation on how to run them.
Note
Docker Desktop for Mac uses a VM behind the scenes to host the Docker runtime environment. By default it allocates 2 GB of RAM to the VM. This is not enough to compile Spicy analzers and will cause an error that looks something like this:
c++: internal compiler error: Killed (program cc1plus)
Please submit a full bug report,
with preprocessed source if appropriate.
See <file:///usr/share/doc/gcc-7/README.Bugs> for instructions.
This is due to the VM hitting an out-of-memory condition. To avoid this you will need to allocate more RAM to the VM. Click on the Docker Icon in your menubar and select “Preferences”. Click on the “Advanced” tab and then use the slider to select 8 GB of RAM. Docker Desktop will restart and then you will be ready to go.
1.3. Building from source
1.3.1. Prerequisites
To build Spicy from source, you will need:
For compiling the toolchain:
For testing:
For building the documentation:
Python >= 3.4
Sphinx >= 1.8
Pygments >= 2.5
Read the Docs Sphinx Theme (
pip install sphinx_rtd_theme
)
In the following we record how to get these dependencies in place on some popular platforms. Please file an issue if you have instructions for platforms not yet listed here.
1.3.1.1. Linux
See the corresponding Dockerfiles.
1.3.1.2. macOS
Make sure you have Xcode installed, including its command-line tools
(xcode-select --install
).
If you are using Homebrew:
# brew install bison flex cmake ninja python@3.8 sphinx-doc
# pip3 install btest
If you are using MacPorts:
# port install flex bison cmake ninja python38 py38-pip
# pip install btest
If you want to build the documentation as well, also install
sphinx_rtd_theme
and diagrams
through pip.
1.3.1.3. FreeBSD
See the prepare script coming with the Spicy distribution.
1.3.2. Building Spicy
Get the code:
# git clone --recursive https://github.com/zeek/spicy
The short version to build Spicy is the usual process then:
# ./configure && make && make install
However, you may want to customize the build a bit, see the output
./configure --help
for the available options. In particular, you
can use --prefix=/other/path
to install into something else than
/usr/local
.
The final configure
output will summarize your build’s
configuration.
Note
For developers, the following configure
options may be
particular useful:
--enable-ccache
: use theccache
compiler cache to speed up compilation
--enable-debug
: compile a non-optimized debug version
--enable-sanitizer
: enable address & leak sanitizers
--generator=Ninja
: use the fasterninja
build system instead ofmake
Using Ninja and ccache
will speed up compile times. On Linux,
compiling will also be quite a bit faster if you have the “Gold
linker” available. To check if you do, see if which ld.gold
returns anything. If yes, configure
will automatically pick it
up.
Once you have configured Spicy, running make
will change into the
newly created build
directory and start the compilation there.
Once finished, make test
will execute the test suite. It will take
a bit, but all tests should be passing (unless explicitly reported as
expected to fail). Finally, make install
will install Spicy
system-wide into the configured prefix. If you are installing into a
non-standard location, make sure that <prefix>/bin
is in your
PATH
.
Note
You can also use the Spicy tools directly out of the build
directory without installing; the binaries land in build/bin
.
To build Spicy’s documentation, run make
inside the docs/
directory.
Documentation will then be located in build/doc/html
.
1.4. Parser development setup
In order to speed up compilation of Spicy parsers, users can create a cache of precompiled files. This cache is tied to a specific Spicy version, and needs to be recreated each time Spicy is updated.
To precompile the files execute the following command:
# spicy-precompile-headers
Note
By default the cache is located in the folder
.cache/spicy/<VERSION>
inside the user’s home directory. This
location can be overridden by setting the environment variable
SPICY_CACHE
to a different folder path, both when executing
spicy-precompile-headers
and Spicy toolchain commands.