Installation

This section discusses how to install Verilator.

Package Manager Quick Install

Using a distribution’s package manager is the easiest way to get started. (Note packages are unlikely to have the most recent version, so Git Quick Install might be a better alternative.) To install as a package:

apt-get install verilator   # On Ubuntu

For other distributions, refer to Repology Verilator Distro Packages.

pre-commit Quick Install

You can use Verilator’s pre-commit hook to lint your code before committing it. It encapsulates the Verilator Build Docker Container, so you need docker on your system to use it. The verilator image will be downloaded automatically.

To use the hook, add the following entry to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/verilator/verilator
    rev: v5.026  # or later
    hooks:
      - id: verilator

Git Quick Install

Installing Verilator from Git provides the most flexibility; for additional options and details, see Detailed Build Instructions below.

In brief, to install from git:

# Prerequisites:
#sudo apt-get install git help2man perl python3 make autoconf g++ flex bison ccache
#sudo apt-get install libgoogle-perftools-dev numactl perl-doc
#sudo apt-get install libfl2  # Ubuntu only (ignore if gives error)
#sudo apt-get install libfl-dev  # Ubuntu only (ignore if gives error)
#sudo apt-get install zlibc zlib1g zlib1g-dev  # Ubuntu only (ignore if gives error)

git clone https://github.com/verilator/verilator   # Only first time

# Every time you need to build:
unsetenv VERILATOR_ROOT  # For csh; ignore error if on bash
unset VERILATOR_ROOT  # For bash
cd verilator
git pull         # Make sure git repository is up-to-date
git tag          # See what versions exist
#git checkout master      # Use development branch (e.g. recent bug fixes)
#git checkout stable      # Use most recent stable release
#git checkout v{version}  # Switch to specified release version

autoconf         # Create ./configure script
./configure      # Configure and create Makefile
make -j `nproc`  # Build Verilator itself (if error, try just 'make')
sudo make install

Detailed Build Instructions

This section describes details of the build process and assumes you are building from Git. For using a pre-built binary for your Linux distribution, see instead Package Manager Quick Install.

OS Requirements

Verilator is developed and has primary testing on Ubuntu, with additional testing on FreeBSD and Apple OS-X. Versions have also been built on Red Hat Linux, other flavors of GNU/Linux-ish platforms, Windows Subsystem for Linux (WSL2), Windows under Cygwin, and Windows under MinGW (gcc -mno-cygwin). Verilated output (not Verilator itself) compiles under all the options above, plus using MSVC++.

Install Prerequisites

To build or run Verilator, you need these standard packages:

sudo apt-get install git help2man perl python3 make
sudo apt-get install g++  # Alternatively, clang
sudo apt-get install libgz  # Non-Ubuntu (ignore if gives error)
sudo apt-get install libfl2  # Ubuntu only (ignore if gives error)
sudo apt-get install libfl-dev  # Ubuntu only (ignore if gives error)
sudo apt-get install zlibc zlib1g zlib1g-dev  # Ubuntu only (ignore if gives error)

To build or run Verilator, the following are optional but should be installed for good performance:

sudo apt-get install ccache  # If present at build, needed for run
sudo apt-get install mold  # If present at build, needed for run
sudo apt-get install libgoogle-perftools-dev numactl

The following is optional but is recommended for nicely rendered command line help when running Verilator:

sudo apt-get install perl-doc

To build Verilator you will need to install these packages; these do not need to be present to run Verilator:

sudo apt-get install git autoconf flex bison

Those developing Verilator itself may also want these (see internals.rst):

sudo apt-get install clang clang-format-14 cmake gdb gprof graphviz lcov
sudo apt-get install python3-clang yapf3 bear jq
sudo pip3 install sphinx sphinx_rtd_theme sphinxcontrib-spelling breathe ruff
sudo pip3 install git+https://github.com/antmicro/astsee.git
cpan install Pod::Perldoc

Install SystemC

If you will be using SystemC (vs straight C++ output), download SystemC. Follow their installation instructions. You will need to set the SYSTEMC_INCLUDE environment variable to point to the include directory with systemc.h in it, and set the SYSTEMC_LIBDIR environment variable to point to the directory with libsystemc.a in it.

Install GTKWave

To make use of Verilator FST tracing you will want GTKwave installed, however this is not required at Verilator build time.

Install Z3

In order to use constrained randomization the Z3 Theorem Prover must be installed, however this is not required at Verilator build time. There are other compatible SMT solvers, like CVC5/CVC4, but they are not guaranteed to work. Since different solvers are faster for different scenarios, the solver to use at run-time can be specified by the environment variable VERILATOR_SOLVER.

Obtain Sources

Get the sources from the git repository: (You need to do this only once, ever.)

git clone https://github.com/verilator/verilator   # Only first time
## Note the URL above is not a page you can see with a browser; it's for git only

Enter the checkout and determine what version/branch to use:

cd verilator
git pull        # Make sure we're up-to-date
git tag         # See what versions exist
#git checkout master      # Use development branch (e.g. recent bug fix)
#git checkout stable      # Use most recent release
#git checkout v{version}  # Switch to specified release version

Auto Configure

Create the configuration script:

autoconf        # Create ./configure script

Eventual Installation Options

Before configuring the build, you must decide how you’re going to eventually install Verilator onto your system. Verilator will be compiling the current value of the environment variables VERILATOR_ROOT, VERILATOR_SOLVER, SYSTEMC_INCLUDE, and SYSTEMC_LIBDIR as defaults into the executable, so they must be correct before configuring.

These are the installation options:

1. Run-in-Place from VERILATOR_ROOT

Our personal favorite is to always run Verilator in-place from its Git directory (don’t run make install). This allows the easiest experimentation and upgrading, and allows many versions of Verilator to co-exist on a system.

export VERILATOR_ROOT=`pwd`   # if your shell is bash
setenv VERILATOR_ROOT `pwd`   # if your shell is csh
./configure
# Running will use files from $VERILATOR_ROOT, so no install needed

Note after installing (see Installation), a calling program or shell must set the environment variable VERILATOR_ROOT to point to this Git directory, then execute $VERILATOR_ROOT/bin/verilator, which will find the path to all needed files.

2. Install into a Specific Prefix

You may be an OS package maintainer building a Verilator package, or you may eventually be installing onto a project/company-wide “CAD” tools disk that may support multiple versions of every tool. Tell configure the eventual destination directory name. We recommend that the destination location include the Verilator version name:

unset VERILATOR_ROOT      # if your shell is bash
unsetenv VERILATOR_ROOT   # if your shell is csh
# For the tarball, use the version number instead of git describe
./configure --prefix /CAD_DISK/verilator/`git describe | sed "s/verilator_//"`

Note after installing (see Installation), you need to add the path to the bin directory to your PATH. Or, if you use modulecmd, you’ll want a module file like the following:

set install_root /CAD_DISK/verilator/{version-number-used-above}
unsetenv VERILATOR_ROOT
prepend-path PATH $install_root/bin
prepend-path MANPATH $install_root/man
prepend-path PKG_CONFIG_PATH $install_root/share/pkgconfig

3. Install System Globally

The final option is to eventually install Verilator globally, using configure’s default system paths:

unset VERILATOR_ROOT      # if your shell is bash
unsetenv VERILATOR_ROOT   # if your shell is csh
./configure

Then after installing (see Installation), the binaries should be in a location already in your $PATH environment variable.

Configure

The command to configure the package was described in the previous step. Developers should configure to have more complete developer tests. Additional packages may be required for these tests.

export VERILATOR_AUTHOR_SITE=1    # Put in your .bashrc
./configure --enable-longtests  ...above options...

Compile

Compile Verilator:

make -j `nproc`  # Or if error on `nproc`, the number of CPUs in system

Test

Check the compilation by running self-tests:

make test

Install

If you used any install option other than the 1. Run-in-Place from VERILATOR_ROOT scheme, install the files:

make install

Verilator Build Docker Container

This Verilator Build Docker Container is set up to compile and test a Verilator build. It uses the following parameters:

The container is published as verilator/verilator-buildenv on docker hub.

To run the basic build using the current Verilator master:

docker run -ti verilator/verilator-buildenv

To also run tests:

docker run -ti verilator/verilator-buildenv test

To change the compiler:

docker run -ti -e CC=clang-10 -e CXX=clang++-10 verilator/verilator-buildenv test

The tests that involve gdb are not working due to security restrictions. To run those too:

docker run -ti -e CC=clang-10 -e CXX=clang++-10 --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test

Rather then building using a remote git repository you may prefer to use a working copy on the local filesystem. Mount the local working copy path as a volume and use that in place of git. When doing this be careful to have all changes committed to the local git area. To build the current HEAD from top of a repository:

docker run -ti -v ${PWD}:/tmp/repo -e REPO=/tmp/repo -e REV=`git rev-parse --short HEAD` --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test

Rebuilding

To rebuild the Verilator-buildenv docker image, run:

docker build .

This will also build SystemC under all supported compiler variants to reduce the SystemC testing time.

Verilator Executable Docker Container

The Verilator Executable Docker Container allows you to run Verilator easily as a docker image, e.g.:

docker run -ti verilator/verilator:latest --version

This will pull the container from docker hub, run the latest Verilator and print Verilator’s version.

Containers are automatically built and pushed to docker hub for all released versions, so you may easily compare results across versions, e.g.:

docker run -ti verilator/verilator:4.030 --version

Verilator needs to read and write files on the local system. To simplify this process, use the verilator-docker convenience script. This script takes the version number, and all remaining arguments are passed through to Verilator. e.g.:

./verilator-docker 4.030 --version

or

./verilator-docker 4.030 --cc test.v

If you prefer not to use verilator-docker you must give the container access to your files as a volume with appropriate user rights. For example to Verilate test.v:

docker run -ti -v ${PWD}:/work --user $(id -u):$(id -g) verilator/verilator:latest --cc test.v

This method can only access files below the current directory. An alternative is setup the volume -workdir.

You can also work in the container by setting the entrypoint (don’t forget to mount a volume if you want your work persistent):

docker run -ti --entrypoint /bin/bash verilator/verilator:latest

You can also use the container to build Verilator at a specific commit:

docker build --build-arg SOURCE_COMMIT=<commit> .

Internals

The Dockerfile builds Verilator and removes the tree when completed to reduce the image size. The entrypoint is a wrapper script (verilator-wrap.sh). That script 1. calls Verilator, and 2. copies the Verilated runtime files to the obj_dir or the -Mdir respectively. This allows the user to have the files to they may later build the C++ output with the matching runtime files. The wrapper also patches the Verilated Makefile accordingly.

A hook is also defined and run by Docker Hub via automated builds.