|Logo| ====================== Verilator Installation ====================== .. contents:: :depth: 3 Introduction ============ This discusses how to install Verilator. For more general information please see `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 `Running Verilator <#_running_verilator>`__. Docker ------ Verilator is available in pre-built Docker containers. See https://github.com/verilator/verilator/blob/master/ci/docker/run/README.rst Git --- Installing Verilator with Git provides the most flexibility. For additional options and details see the additional sections below. In brief: :: # 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://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 # 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 `Running Verilator <#_running_verilator>`__. 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 `Install From a Package Manager <#_install_from_a_package_manager>`__. OS Requirements --------------- Verilator is developed and has primary testing on Ubuntu, with additional testing on FreeBSD and Apple OS-X. Versions have also built on Redhat Linux, HPUX and Solaris. It should run with minor porting on any GNU/Linux-ish platform. Verilator also works on Windows under Cygwin, and Windows under MinGW (gcc -mno-cygwin). Verilated output (not Verilator itself) compiles under all the options above, plus MSVC++. Install Prerequisites --------------------- To build or run Verilator you need these standard packages: :: sudo apt-get install 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 libfl-dev zlibc zlib1g zlib1g-dev # Ubuntu only (ignore if gives error) To build or run 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 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 asciidoctor graphviz cmake clang clang-format gprof lcov 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 ``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 `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 `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://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 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 `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 <#_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 `Verilator manual (HTML) `__, or `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, go to `Verilator announcement repository `__ and follow the instructions there. Directory Structure =================== Some relevant files and directories in this package are as follows: :: Changes => Version history README.rst => 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 src/ => Translator source code test_regress => Internal tests For files created after a design is Verilated, see the `Verilator manual (HTML) `__, or `Verilator manual (PDF) `__. License ======= Copyright 2008-2021 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. .. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png