diff --git a/MANIFEST.SKIP b/MANIFEST.SKIP index 828d6f3ca..b0f22bf37 100644 --- a/MANIFEST.SKIP +++ b/MANIFEST.SKIP @@ -30,8 +30,10 @@ /cov_work/ /logs/ ^Makefile$ +README.html bin/verilator_bin.* bin/verilator_coverage_bin.* +docs/.*\.html$ docs/Makefile$ docs/doxygen-doc/.* examples/xml_py/copied/ diff --git a/Makefile.in b/Makefile.in index a495aa0ef..75a7e98e5 100644 --- a/Makefile.in +++ b/Makefile.in @@ -115,8 +115,9 @@ SUBDIRS = src test_regress \ examples/make_tracing_sc \ examples/make_protect_lib \ -INFOS = README README.html README.pdf \ - verilator.txt verilator.html verilator.pdf +INFOS = verilator.txt verilator.html verilator.pdf + +INFOS_OLD = README README.html README.pdf # Files that can be generated, but should be up to date for a distribution. DISTDEP = info Makefile @@ -127,6 +128,7 @@ DISTFILES_INC = $(INFOS) .gitignore \ Changes \ LICENSE \ MANIFEST.SKIP \ + README.adoc \ verilator-config.cmake.in \ verilator-config-version.cmake.in \ bin/verilator \ @@ -142,6 +144,7 @@ DISTFILES_INC = $(INFOS) .gitignore \ docs/TODO \ docs/doxygen-mainpage \ docs/doxygen.config \ + docs/install.adoc \ docs/internals.adoc \ docs/verilator_logo.png \ install-sh configure *.pod \ @@ -281,22 +284,6 @@ verilator.pdf: ${srcdir}/bin/verilator Makefile $(POD2LATEXFIX) pdflatex verilator.tex -rm -f verilator.toc verilator.aux verilator.idx verilator.out -README: README.pod - -rm -f $@ - $(POD2TEXT) --loose $< > $@ - -README.html: README.pod - pod2html $< >$@ - -# PDF needs DIST variables; but having configure.ac as dependency isn't detected -README.pdf: README.pod Makefile $(POD2LATEXFIX) - pod2latex --full --out README.tex $< - $(PERL) $(POD2LATEXFIX) "$(DISTTITLE) README File" "${DISTDATE}" < README.tex > README2.tex - mv README2.tex README.tex - pdflatex README.tex - pdflatex README.tex - -rm -f README.toc README.aux README.idx README.out - # See uninstall also - don't put wildcards in this variable, it might uninstall other stuff VL_INST_BIN_FILES = verilator verilator_bin verilator_bin_dbg verilator_coverage_bin_dbg \ verilator_coverage verilator_gantt verilator_includer verilator_profcfunc @@ -529,7 +516,7 @@ clean mostlyclean distclean maintainer-clean:: rm -rf nodist/obj_dir distclean maintainer-clean:: - rm -f *.info* *.1 $(INFOS) $(VL_INST_MAN_FILES) + rm -f *.info* *.1 $(INFOS) $(INFOS_OLD) $(VL_INST_MAN_FILES) rm -f Makefile config.status config.cache config.log TAGS rm -f verilator_bin* verilator_coverage_bin* rm -f bin/verilator_bin* bin/verilator_coverage_bin* diff --git a/README.adoc b/README.adoc new file mode 100644 index 000000000..fa9872541 --- /dev/null +++ b/README.adoc @@ -0,0 +1,140 @@ +// Github doesn't render images unless absolute URL +:!toc: + +ifdef::env-github[] +image:https://img.shields.io/badge/License-LGPL%20v3-blue.svg[license LGPLv3,link=https://www.gnu.org/licenses/lgpl-3.0] +image:https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg[license Artistic-2.0,link=https://opensource.org/licenses/Artistic-2.0] +image:https://api.codacy.com/project/badge/Grade/ff998fdaa6f64b9a95eb5f342ee6bf4d[Code Quality,link=https://www.codacy.com/manual/wsnyder/verilator] +image:https://travis-ci.com/verilator/verilator.svg?branch=master[Build Status (Travis CI),link=https://travis-ci.com/verilator/verilator] +endif::[] + +ifdef::env-github[] +:link_verilator_contributing: link:docs/CONTRIBUTING.adoc +:link_verilator_install: link:docs/install.adoc +endif::[] +ifndef::env-github[] +:link_verilator_contributing: link:docs/CONTRIBUTING.adoc +:link_verilator_install: https://verilator.org/install +endif::[] + +== Welcome to Verilator + +[cols="a,a",indent=0,frame="none"] +|=== +^.^| *Welcome to Verilator, the fastest free Verilog HDL simulator.* ++++
+++ • Accepts synthesizable Verilog or SystemVerilog ++++
+++ • Performs lint code-quality checks ++++
+++ • Compiles into multithreaded {cpp}, SystemC, or (soon) {cpp}-under-Python ++++
+++ • Creates XML to front-end your own tools +<.^|image:https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200] + +>.^|image:https://www.veripool.org/img/verilator_multithreaded_performance_bg-min.png[,388,178] +^.^| *Fast* ++++
+++ • Outperforms many commercial simulators ++++
+++ • Single- and multi-threaded output models + +^.^| *Widely Used* ++++
+++ • Wide industry and academic deployment ++++
+++ • Out-of-the-box support from Arm, and RISC-V vendor IP +<.^|image:https://www.veripool.org/img/verilator_usage_400x200-min.png[,400,200] + +>.^|image:https://www.veripool.org/img/chips_alliance_logo_225x75-min.png[CHIPS Alliance,link=https://chipsalliance.org] +image:https://www.veripool.org/img/osi_logo_125x125-min.png[,125,125] +^.^| *Community Driven & Openly Licensed* ++++
+++ • Guided by the https://chipsalliance.org/[CHIPS Alliance] and https://www.linuxfoundation.org/[Linux Foundation] ++++
+++ • Open, and free as in both speech and beer ++++
+++ • More simulation for your verification budget +|=== + +== What Verilator Does + +Verilator is invoked with parameters similar to GCC or Synopsys's VCS. It +"Verilates" the specified synthesizable Verilog or SystemVerilog code by +reading it, performing lint checks, and optionally inserting assertion +checks and coverage-analysis points. It outputs single- or multi-threaded +.cpp and .h files, the "Verilated" code. + +The user writes a little {cpp}/SystemC wrapper file, which instantiates the +"Verilated" model of the user's top level module. These {cpp}/SystemC +files are then compiled by a {cpp} compiler (gcc/clang/MSVC++). The +resulting executable performs the design simulation. Verilator also +supports linking its generated libraries, optionally encrypted, into other +simulators. + +Verilator may not be the best choice if you are expecting a full featured +replacement for NC-Verilog, VCS or another commercial Verilog simulator, or +if you are looking for a behavioral Verilog simulator e.g. for a quick +class project (we recommend http://iverilog.icarus.com[Icarus Verilog] for +this.) However, if you are looking for a path to migrate synthesizable +Verilog to {cpp} or SystemC, and your team is comfortable writing just a +touch of {cpp} code, Verilator is the tool for you. + +== Performance + +Verilator does not simply convert Verilog HDL to {cpp} or SystemC. Rather +than only translate, Verilator compiles your code into a much faster +optimized and optionally thread-partitioned model, which is in turn wrapped +inside a {cpp}/SystemC/Python module. The results are a compiled Verilog +model that executes even on a single-thread over 10x faster than standalone +SystemC, and on a single thread is about 100 times faster than interpreted +Verilog simulators such as http://iverilog.icarus.com[Icarus +Verilog]. Another 2-10x speedup might be gained from multithreading +(yielding 200-1000x total over interpreted simulators). + +Verilator has typically similar or better performance versus the commercial +Verilog simulators (Carbon Design Systems Carbonator, Modelsim, Cadence +Incisive/NC-Verilog, Synopsys VCS, VTOC, and Pragmatic CVer/CVC). But, +Verilator is free, so you can spend on computes rather than licenses. Thus +Verilator gives you more cycles/dollar than anything else available. + +For more information on how Verilator stacks up to some of the other +commercial and free Verilog simulators, see the +https://www.veripool.org/verilog_sim_benchmarks.html[Verilog Simulator +Benchmarks]. (If you benchmark Verilator, please see the notes in the +https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)], and also +if possible post on the forums the results; there may be additional tweaks +possible.) + +== Installation + +== Documentation + +For more information: + +* {link_verilator_install}[Verilator installation and package directory + structure]. + +* https://verilator.org/verilator_doc.html[Verilator manual (HTML)], +or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)]. + +* https://verilator.org/forum[Verilator forum]. + +== Community Supported + +Verilator is a community project, guided by the +https://chipsalliance.org/[CHIPS Alliance] under the +https://www.linuxfoundation.org/[Linux Foundation]. + +We appreciate and welcome your contributions in whatever form; please see +{link_verilator_contributing}[Contributing to Verilator]. Thanks to our +https://verilator.org/verilator_doc.html#CONTRIBUTORS[Contributors and +Sponsors]. + +== Related Projects + +* http://gtkwave.sourceforge.net/[GTKwave] - Waveform viewer for Verilator +traces. + +* http://iverilog.icarus.com[Icarus Verilog] - Icarus is a full featured +interpreted Verilog simulator. If Verilator does not support your needs, +perhaps Icarus may. + +== Open License + +Verilator is Copyright 2003-2019 by Wilson Snyder. (Report bugs to +https://verilator.org/issues[Verilator Issues].) + +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.) diff --git a/README.pod b/README.pod deleted file mode 100644 index ddb5e4699..000000000 --- a/README.pod +++ /dev/null @@ -1,297 +0,0 @@ -# DESCRIPTION: DOCUMENT source run through perl to produce README file -# Use 'make README' to produce the output file - -=pod - -=begin html - - - - - - -=end html - -=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. - -=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 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++ 2008 and newer. - -=head1 INSTALLATION - -The following are detailed installation instructions. -Alternatively, for a quick summary please see -L. - -=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. -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, C (or C), and -C (or C) packages. To compile Verilator in addition to the above you need the C, -C and C packages installed. - - sudo apt-get install git make autoconf g++ flex bison # 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. 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 and C (and on -Ubuntu C C C) 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 installing 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, 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 to compile Verilator. - -=item - -Type C to check the compilation. - -=item - -If you used the prefix scheme, now do a C. - -=item - -You may now wish to consult the examples directory. Type C 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 (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/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 - 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.) - -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. diff --git a/docs/.gitignore b/docs/.gitignore index f3c7a7c5d..e1ce07996 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,4 @@ +*.1 +*.html +*.pdf Makefile diff --git a/docs/Makefile.in b/docs/Makefile.in index 61156f3da..da9baecb4 100644 --- a/docs/Makefile.in +++ b/docs/Makefile.in @@ -23,6 +23,7 @@ #### Start of system configuration section. #### +ASCIIDOCTOR = asciidoctor DOXYGEN = doxygen #### End of system configuration section. #### @@ -33,6 +34,9 @@ DOXYGEN = doxygen default: @echo "error: make not supported here, run 'make docs' from Verilator top-level" +%.html: %.adoc + $(ASCIIDOCTOR) $< -n -o $@ + clean mostlyclean distclean maintainer-clean:: rm -f $(SCRIPTS) *.tmp rm -f *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.log @@ -41,7 +45,7 @@ clean mostlyclean distclean maintainer-clean:: rm -f *.tex distclean maintainer-clean:: - rm -f *.info* *.1 $(INFOS) + rm -f *.info* *.1 *.html *.pdf $(INFOS) rm -f Makefile .PHONY: doxygen diff --git a/docs/TODO b/docs/TODO old mode 100755 new mode 100644 diff --git a/docs/install.adoc b/docs/install.adoc new file mode 100644 index 000000000..a454d663f --- /dev/null +++ b/docs/install.adoc @@ -0,0 +1,294 @@ += 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 http://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. 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 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 + +# 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 <>. + +== 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 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 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 + +==== 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 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 + +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, login to +http://www.veripool.org[Veripool], and click the "watch" button near the +top right under http://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 + 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. diff --git a/docs/internals.adoc b/docs/internals.adoc index e460c4778..bde0e2c3c 100644 --- a/docs/internals.adoc +++ b/docs/internals.adoc @@ -9,7 +9,7 @@ image::https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200,role= This file discusses internal and programming details for Verilator. It's a reference for developers and debugging problems. -See also the Verilator internals presentation at http://www.veripool.org. +See also the Verilator internals presentation at https://www.veripool.org. == Code Flows