# DESCRIPTION: DOCUMENT source run through perl to produce README file
# Use 'make README' to produce the output file

=pod

=head1 NAME

Welcome to Verilator.  This is the Verilator package's README file.

This document describes how to initially install Verilator.  For more
general information please see L<http://verilator.org>.

=head1 DESCRIPTION

Verilator is a simulator which "Verilates" synthesizable (generally not
behavioral) Verilog code into "Verilated" C++ or SystemC code.

Verilator is invoked with parameters similar to GCC or Synopsys's VCS.  It
reads the specified Verilog code, lints it, and optionally adds coverage
code.  For C++ format, it outputs .cpp and .h files.  For SystemC format,
it outputs .cpp and .h files using the standard SystemC headers.

The resulting files are then compiled with C++.  The user writes a little
C++ wrapper file, which instantiates the top level module.  This is
compiled in C++, and linked with the Verilated files.

The resulting executable will perform the actual simulation.

=head1 SUPPORTED SYSTEMS

Verilator is developed and has primary testing on Ubuntu.  Versions have
also built on Redhat Linux, Macs OS-X, HPUX and Solaris.  It should run
with minor porting on any Linix-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++ 2008 and newer.

=head1 INSTALLATION

The following are detailed installation instructions.
Alternatively, for a quick summary please see
L<http://www.veripool.org/projects/verilator/wiki/Installing>.

=over 4

=item

Obtain binary or sources:

There are three methods to obtain Verilator, a prebuilt binary as part of
your Linux distribution, via git, or using a tarball.  If you will be
modifying Verilator, you should use the "git" method as it will let you
track changes and hopefully contribute in the future.

=over 4

=item

Prebuilt binary:

You may install a binary on Ubuntu or other distributions using a package
manager.  This is unlikely to be the most recent version.

  apt-get install verilator

You may now skip the remaining installation steps.

=item

Git:

Get the sources from the repository.

  git clone http://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

=item

Tarball:

Get a recent tarball package from L<http://www.veripool.org/verilator>.
Click the "Download" tab, scroll down to the latest package
(i.e. verilator-#.###.tgz), download it, and decompress with:

    tar xvzf verilator_#-###.tgz

=back

=item

Install prerequisites:

=over 4

=item

To use Verilator you will need the C<perl>, C<make> (or C<gmake>), and
C<g++> (or C<clang>) packages. To compile Verilator in addition to the above you need the C<flex>,
C<bison> and C<texi2html> packages installed.

  sudo apt-get install git make autoconf g++ flex bisonz   # First time prerequisites
  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)

=item

If you will be using SystemC (vs straight C++ output), download SystemC
from L<http://www.systemc.org>.  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.)

=item

To use Verilator FST tracing you will need the C<gtkwave> and C<libgz> (and on
Ubuntu C<zlibc> C<zlib1g> C<zlib1g-dev>) packages installed.

=back

=item

Prepare for building:

  cd verilator                # Needed if not already in the package
  unsetenv VERILATOR_ROOT     # For csh; ignore error if on bash
  unset VERILATOR_ROOT        # For bash; ignore error if on bash
  # If using git:
    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
  #
  autoconf                    # Create ./configure script

=item

Installation Choices

You have to decide how you're going to eventually install the kit.

Note Verilator builds the current value of VERILATOR_ROOT, SYSTEMC_INCLUDE,
and SYSTEMC_LIBDIR as defaults into the executable, so try to have them
correct before configuring.

=over 4

=item 1.

Our personal favorite is to always run Verilator from its git directory.
This allows the easiest experimentation and upgrading, and allows many
versions of Verilator to co-exist on a system. To run you point to the
program's files, no install is needed.

    export VERILATOR_ROOT=`pwd`   # if your shell is bash
    setenv VERILATOR_ROOT `pwd`   # if your shell is csh
    ./configure

Note after installing (below steps), a calling program should 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.

=item 2.

You may eventually be instaling onto a project/company-wide "CAD" tools
disk that may support multiple versions of every tool.

    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 C<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

=item 3.

The next option is to eventually install it 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.

=item 4.

Finally, you may eventually install it 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.

=back

Note all of the options above did:

    ./configure  ... some options ...

Add to this line C<--enable-longtests> for more complete developer tests.
Additional packages may be required for these tests.

=item

Type C<make> to compile Verilator.

=item

Type C<make test> to check the compilation.

=item

If you used the prefix scheme, now do a C<make install>.

=item

You may now wish to consult the examples directory. Type C<make> inside any
example directory to run the example.

=back

=head1 USAGE DOCUMENTATION

Detailed documentation and the man page can be seen by running:

    bin/verilator --help

or reading verilator.pdf in the same directory as this README.

or see L<https://www.veripool.org/ftp/verilator_doc.pdf> (which is the most
recent version and thus may differ in some respects from the version you installed).

=head1 PACKAGE DIRECTORY STRUCTURE

The directories in the package directory are as follows:

    Changes                     => Version history
    bin/verilator               => Compiler Wrapper invoked to Verilate code
    docs/                       => Additional documentation
    examples/hello_world_c      => Example simple Verilog->C++ conversion
    examples/hello_world_sc     => Example simple Verilog->SystemC conversion
    examples/tracing_c          => Example Verilog->C++ with tracing
    examples/tracing_sc         => Example Verilog->SystemC with tracing
    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
    include/verilated.v         => Stub defines for linting
    src/                        => Translator source code
    test_regress                => Internal tests
    verilator.pdf               => Primary documentation
    verilator.txt               => Primary documentation (text)

For files created after Verilation, see the manual.

=head1 DISTRIBUTION

This package is Copyright 2003-2019 by Wilson Snyder.  (Report bugs to
L<http://www.veripool.org/>.)

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.  (See the documentation for more
details.)

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
more details.