= Verilator Installation :toc: right // Github doesn't render unless absolute URL image::https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200,role="right"] == Introduction This discusses how to install Verilator. For more general information please see https://verilator.org[verilator.org]. == Quick-start === Install From a Package Manager 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, below, maybe a better alternative.) To install as a package: apt-get install verilator If this works, skip down to <>. === Git Alternatively, installing Verilator with Git provides the most flexibility. For additional options and details see the additional sections below. ==== Unix Quick-start In brief: // Also update README .... # Prerequisites: #sudo apt-get install git make autoconf g++ flex bison #sudo apt-get install libfl2 # Ubuntu only (ignore if gives error) #sudo apt-get install libfl-dev # Ubuntu only (ignore if gives error) git clone https://git.veripool.org/git/verilator # Only first time ## Note the URL above is not a page you can see with a browser, it's for git only # 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 make sudo make install # Now see "man verilator" or online verilator.pdf's for the example tutorials .... If this works, skip down to <>. ==== Windows Quick-start Cygwin builds should work similar to Unix builds. Cmake-based building is the long-term goal, and while the `verilator` binary can be currently built, the **cmake-based Windows builds are experimental and currently exempt from test suite coverage**. Cmake-based installation hasn't been implemented yet and has to be done manually. Assuming you have the https://chocolatey.org[Chocolatey] package manager installed, as well as a build environment (MinGW or MSVS): .... :: Prerequisites choco install activeperl ninja winflexbison3 git :: Build git clone https://git.veripool.org/git/verilator verilator cmake -G Ninja -S verilator -B verilator-build cmake --build verilator-build --config Release .... Verilator is built, statically linked, under `./verilator-build/bin`. The binary itself has no other runtime dependencies, but it's expected to be invoked via the `bin/verilator` Perl wrapper. == Detailed Build Instructions This section describes details of the build process, and assumes you are building from Git or a tarball. For using a pre-built binary for your Linux distribution, see instead <>. === OS Requirements Verilator is developed and has primary testing on Ubuntu. Versions have also built on Redhat Linux, Apple macOS, HPUX and Solaris. It should run with minor porting on any GNU/Linux-ish platform. Verilator also works on Windows - natively using either MinGW (`gcc -mno-cygwin`) or MS Visual C++ as the compiler, and under Cygwin. Verilated output also compiles under all the options above. === Install Prerequisites ==== Linux To build Verilator you will need to install some standard packages: sudo apt-get install git sudo apt-get install autoconf sudo apt-get install flex bison Additionally, to build or run Verilator you need these standard packages: sudo apt-get install perl python3 sudo apt-get install make sudo apt-get install g++ # Alternatively, clang sudo apt-get install libgz # Non-Ubuntu (ignore if gives error) sudo apt-get install libfl2 libfl-dev zlibc zlib1g zlib1g-dev # Ubuntu only (ignore if gives error) Those developing Verilator may also want these (see internals.adoc): sudo apt-get install gdb asciidoctor graphviz cpan install Pod::Perldoc cpan install Unix::Processors ==== Windows It's most convenient to install all the prerequisites using the https://chocolatey.org[Chocolatey] package manager. You can install it from an administrative powershell window as follows: Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1')) Verilator can be built natively, i.e. without using Cygwin nor MSYS, using either MS Visual Studio 2017 or later, or MinGW 7.3 or later. Those are easily installed using Chocolatey: .... :: Only one needed choco install visualstudio2019buildtools :: or choco install mingw .... Other prerequisites are Git, Perl, CMake, and Ninja: choco install activeperl git cmake ninja ==== Install SystemC If you will be using SystemC (vs straight C++ output), download http://www.systemc.org[SystemC]. Follow their installation instructions. You will need to set `SYSTEMC_INCLUDE` to point to the include directory with systemc.h in it, and `SYSTEMC_LIBDIR` to points to the directory with libsystemc.a in it. (Older installations may set `SYSTEMC` and `SYSTEMC_ARCH` instead.) ==== Install GTKWave To make use of Verilator FST tracing you will want http://gtkwave.sourceforge.net/[GTKwave] installed, however this is not required at Verilator build time. === Obtain Sources You may use Git or a tarball for the sources. Git is the supported option. (If using a historical build that uses a tarball, tarballs are obtained from https://www.veripool.org/projects/verilator/wiki/Download[Verilator Downloads]; we presume you know how to use it, and is not described here.) Get the sources from the repository: (You need do this only once, ever.) git clone https://git.veripool.org/git/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 === Build Introduction There are currently two ways to build Verilator: . The autoconf-based build is the primary supported build. . The CMake-based build is available on Windows. Neither installation nor tests are implemented in the cmake files yet, thus manual installation and testing is necessary if desired. + The cmake build is currently only tested on Windows, and is fairly simple once the prerequisites are in place. See <> for details. The remaining build steps below apply to the autoconf-based build. === Auto Configure Create the configuration script: autoconf # Create ./configure script === Eventual Installation Options Before configuring the build, you have to decide how you're going to eventually install the kit. Verilator will be compiling the current value of `VERILATOR_ROOT`, `SYSTEMC_INCLUDE`, and `SYSTEMC_LIBDIR` as defaults into the executable, so they must be correct before configuring. These are the 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 CAD Disk You may eventually be installing onto a project/company-wide "CAD" tools disk that may support multiple versions of every tool. Target the build to a destination directory name that includes 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 http://modules.sourceforge.net/[modulecmd], you'll want a module file like the following: .modulecmd's verilator/version file ---- 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 `$PATH`. ==== 4. Install System Globally The final option is to eventually install Verilator globally, using the normal system paths: unset VERILATOR_ROOT # if your shell is bash unsetenv VERILATOR_ROOT # if your shell is csh ./configure Then after installing (below) the binary directories should already be in your `$PATH`. === 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 === Test Check the compilation by running self-tests: make test === Install If you used any but the <<1. Run-in-Place from VERILATOR_ROOT>> scheme, install to the OS-standard place: make install == Running Verilator To run Verilator, see the example sections in the https://verilator.org/verilator_doc.html[Verilator manual (HTML)], or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)]. Also see the `examples/` directory that is part of the kit, and is installed (in a OS-specific place, often in e.g. `/usr/local/share/verilator/examples`). cd examples/make_hello_c make Note if you did a `make install` above you should not have `VERILATOR_ROOT` set in your environment; it is built into the executable. == Announcements To get notified of new releases, login to https://www.veripool.org[Veripool], and click the "watch" button near the top right under https://www.veripool.org/projects/verilator/news[Verilator News]. == Directory Structure Some relevant files and directories in this package are as follows: Changes => Version history README.adoc => This document bin/verilator => Compiler wrapper invoked to Verilate code docs/ => Additional documentation examples/make_hello_c => Example GNU-make simple Verilog->C++ conversion examples/make_hello_sc => Example GNU-make simple Verilog->SystemC conversion examples/make_tracing_c => Example GNU-make Verilog->C++ with tracing examples/make_tracing_sc => Example GNU-make Verilog->SystemC with tracing examples/make_protect_lib => Example using --protect-lib examples/cmake_hello_c => Example building make_hello_c with CMake examples/cmake_hello_sc => Example building make_hello_sc with CMake examples/cmake_tracing_c => Example building make_tracing_c with CMake examples/cmake_tracing_sc => Example building make_tracing_sc with CMake examples/cmake_protect_lib => Example building make_protect_lib with CMake include/ => Files that should be in your -I compiler path include/verilated*.cpp => Global routines to link into your simulator include/verilated*.h => Global headers include/verilated.mk => Common Makefile platform/win32 => Windows-specific implementations of missing Posix functionality src/ => Translator source code test_regress => Internal tests For files created after a design is Verilated, see the https://verilator.org/verilator_doc.html[Verilator manual (HTML)], or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)]. == License Copyright 2008-2019 by Wilson Snyder. Verilator is free software; you can redistribute it and/or modify it under the terms of either the GNU Lesser General Public License Version 3 or the Perl Artistic License Version 2.0.