363 lines
13 KiB
Plaintext
363 lines
13 KiB
Plaintext
= 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 <<Running Verilator>>.
|
|
|
|
=== 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 <<Running Verilator>>.
|
|
|
|
==== 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 <<Install From a Package Manager>>.
|
|
|
|
=== 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 <<Windows Quick-start>> 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.
|