mirror of
https://github.com/verilator/verilator.git
synced 2025-01-01 04:07:34 +00:00
308 lines
11 KiB
Plaintext
308 lines
11 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>>.
|
|
|
|
=== Docker
|
|
|
|
Verilator is available in pre-built Docker containers. See
|
|
https://github.com/verilator/verilator/blob/master/ci/docker/run/README.adoc
|
|
|
|
=== Git
|
|
|
|
Installing Verilator with Git provides the most flexibility.
|
|
For additional options and details see the additional sections below. 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>>.
|
|
|
|
== 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 OS-X, 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
|
|
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)
|
|
|
|
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
|
|
|
|
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
|
|
sudo apt-get install autoconf flex bison
|
|
|
|
Those developing Verilator itself may also want these (see internals.adoc):
|
|
|
|
sudo apt-get install gdb asciidoctor graphviz cmake clang-format
|
|
cpan install Pod::Perldoc
|
|
cpan install Unix::Processors
|
|
cpan install Parallel::Forker
|
|
cpan install Bit::Vector
|
|
|
|
==== Install SystemC
|
|
|
|
If you will be using SystemC (vs straight C++ output), download
|
|
https://www.accellera.org/downloads/standards/systemc[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
|
|
|
|
=== 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, go to
|
|
https://github.com/verilator/verilator-announce[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.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
|
|
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-2020 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.
|
|
// SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
|