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.
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 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 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 gdb graphviz cmake clang clang-format-14 gprof lcov
sudo apt-get install libclang-dev yapf3
sudo pip3 install clang sphinx sphinx_rtd_theme sphinxcontrib-spelling breathe
cpan install Pod::Perldoc
cpan install Parallel::Forker
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.
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
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
,
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. 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 (below steps), 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 location¶
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 (below steps), 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 into a Specific Path¶
You may eventually install Verilator into a specific installation prefix, as most GNU tools support:
unset VERILATOR_ROOT # if your shell is bash
unsetenv VERILATOR_ROOT # if your shell is csh
./configure --prefix /opt/verilator-VERSION
Then after installing (below steps), you will need to add
/opt/verilator-VERSION/bin
to your $PATH
environment variable.
4. 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 (below), 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...
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:
Source repository (default: https://github.com/verilator/verilator)
Source revision (default: master)
Compiler (GCC 10.3.0, clang 10.0.0, default: 10.3.0)
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 install the container, run the latest Verilator and print Verilator’s version.
Containers are automatically built 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.