Update install docs and remove a doc build warning
This commit is contained in:
Cary R
parent
f3506a8c92
commit
42d591d296
|
|
@ -87,7 +87,8 @@ html_theme = 'alabaster'
|
|||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
#html_static_path = ['_static']
|
||||
html_static_path = []
|
||||
|
||||
# Custom sidebar templates, must be a dictionary that maps document names
|
||||
# to template names.
|
||||
|
|
|
|||
|
|
@ -2,24 +2,26 @@
|
|||
Installation Guide
|
||||
==================
|
||||
|
||||
Icarus Verilog may be installed from source code, or from pre-packaged binary
|
||||
distributions. If you don't have need for the very latest, and prepackaged
|
||||
binaries are available, that would be the best place to start.
|
||||
Icarus Verilog may be installed from source code (either from ``git`` or a
|
||||
released `tar/zip` file), or from pre-packaged binary distributions. If you
|
||||
don't have a need for the very latest, and prepackaged binaries are available,
|
||||
that is the easiest place to start.
|
||||
|
||||
Installation From Source
|
||||
------------------------
|
||||
|
||||
Icarus is developed for Unix-like environments but can also be compiled on
|
||||
Windows systems using the Cygwin environment or MinGW compilers. The following
|
||||
instructions are the common steps for obtaining the Icarus Verilog source,
|
||||
compiling and installing. Note that there are precompiled and/or prepackaged
|
||||
versions for a variety of systems, so if you find an appropriate packaged
|
||||
version, then that is the easiest way to install.
|
||||
Windows systems using the `Cygwin/MSYS2` environments or `MinGW` compilers. The
|
||||
following instructions are the common steps for obtaining the Icarus Verilog
|
||||
source code, compiling, installing, and checking the compiled code is working
|
||||
properly. Note that there are pre-compiled and/or prepackaged versions for a
|
||||
variety of systems, so if you find an appropriate packaged version, then that
|
||||
is the easiest way to install.
|
||||
|
||||
The source code for Icarus is stored under the git source code control
|
||||
system. You can use git to get the latest development head or the latest of a
|
||||
specific branch. Stable releases are placed on branches, and in particular v11
|
||||
stable releases are on the branch "v11-branch" To get the development version
|
||||
The source code for Icarus is stored under the `git` source code control
|
||||
system. You can use ``git`` to get the latest development head or the latest of
|
||||
a specific branch. Stable releases are placed on branches, and in particular V12
|
||||
stable releases are on the branch "v12-branch" To get the development version
|
||||
of the code follow these steps::
|
||||
|
||||
% git config --global user.name "Your Name Goes Here"
|
||||
|
|
@ -29,7 +31,7 @@ of the code follow these steps::
|
|||
The first two lines are optional and are used to tell git who you are. This
|
||||
information is important if/when you submit a patch. We suggest that you add
|
||||
this information now so you don't forget to do it later. The clone will create
|
||||
a directory, named iverilog, containing the source tree, and will populate
|
||||
a directory, named `iverilog`, containing the source tree, and will populate
|
||||
that directory with the most current source from the HEAD of the repository.
|
||||
|
||||
Change into this directory using::
|
||||
|
|
@ -37,19 +39,26 @@ Change into this directory using::
|
|||
% cd iverilog
|
||||
|
||||
Normally, this is enough as you are now pointing at the most current
|
||||
development code, and you have implicitly created a branch "master" that
|
||||
development code, and you have implicitly created a branch `master` that
|
||||
tracks the development head. However, If you want to actually be working on
|
||||
the v11-branch (the branch where the latest v11 patches are) then you checkout
|
||||
that branch with the command::
|
||||
the `v12-branch` (the branch where the latest V12 patches are) then you
|
||||
checkout that branch with the command::
|
||||
|
||||
% git checkout --track -b v11-branch origin/v11-branch
|
||||
% git checkout --track -b v12-branch origin/v12-branch
|
||||
|
||||
This creates a local branch that tracks the v11-branch in the repository, and
|
||||
switches you over to your new v11-branch. The tracking is important as it
|
||||
This creates a local branch that tracks the `v12-branch` in the repository, and
|
||||
switches you over to your new `v12-branch`. The tracking is important as it
|
||||
causes pulls from the repository to re-merge your local branch with the remote
|
||||
v11-branch. You always work on a local branch, then merge only when you
|
||||
`v12-branch`. You always work on a local branch, then merge only when you
|
||||
push/pull from the remote repository.
|
||||
|
||||
The choice between the development branch and the latest released branch
|
||||
depends on your stability requirements. The released branch will only get bug
|
||||
fixes. It will not get any enhancements or changes in the compiler output
|
||||
format. Unlike many project the development branch is fairly stable with only
|
||||
occasional periods of instability. We do most of our big changes in side
|
||||
branches and only merge them into the development branch when they are clean.
|
||||
|
||||
Now that you've cloned the repository and optionally selected the branch you
|
||||
want to work on, your local source tree may later be synced up with the
|
||||
development source by using the git command::
|
||||
|
|
@ -59,22 +68,33 @@ development source by using the git command::
|
|||
The git system remembers the repository that it was cloned from, so you don't
|
||||
need to re-enter it when you pull.
|
||||
|
||||
Finally, configuration files are built by the extra step::
|
||||
To build the `configure` script and hash files you need to run the
|
||||
following::
|
||||
|
||||
% sh autoconf.sh
|
||||
% cd ..
|
||||
|
||||
The source is then compiled as appropriate for your system. See the specific
|
||||
build instructions below for your operation system for what to do next.
|
||||
|
||||
You will need autoconf and gperf installed in order for the script to work.
|
||||
If you get errors such as::
|
||||
This is not need for the released `tar/zip` files since they already contain
|
||||
these files. You only need to run this once after cloning. If you are missing
|
||||
``autoconf`` or ``gperf`` then the script will fail::
|
||||
|
||||
Autoconf in root...
|
||||
autoconf.sh: 10: autoconf: not found
|
||||
Precompiling lexor_keyword.gperf
|
||||
autoconf.sh: 13: gperf: not found.
|
||||
|
||||
You will need to install download and install the autoconf and gperf tools.
|
||||
You will need to install the ``autoconf`` and ``gperf`` tools before you can
|
||||
continue.
|
||||
|
||||
The other way to get the source code is to download a released `tar/zip` file::
|
||||
|
||||
% tar -xvzf v13_0.tar.gz
|
||||
or
|
||||
% unzip v13_0.zip
|
||||
|
||||
See the build instructions for your operation system below to know what to do
|
||||
next. Though first determine if there are any extra configuration option you
|
||||
may need.
|
||||
|
||||
Icarus Specific Configuration Options
|
||||
-------------------------------------
|
||||
|
|
@ -93,17 +113,18 @@ All programs or directories are tagged with this suffix. e.g.(iverilog-0.8,
|
|||
vvp-0.8, etc.). The output of iverilog will reference the correct run time
|
||||
files and directories. The run time will check that it is running a file with
|
||||
a compatible version e.g.(you can not run a V0.9 file with the V0.8 run
|
||||
time). ::
|
||||
time).::
|
||||
|
||||
--with-valgrind
|
||||
|
||||
This option adds extra memory cleanup code and pool management code to allow
|
||||
better memory leak checking when valgrind is available. This option is not
|
||||
needed when checking for basic errors with valgrind. ::
|
||||
needed when checking for basic errors with valgrind and should not be used if
|
||||
you just intend to use ``iverilog`` as a simulator. ::
|
||||
|
||||
--enable-libvvp
|
||||
|
||||
The vvp progam is built as a small stub linked to a shared library,
|
||||
The vvp program is built as a small stub linked to a shared library,
|
||||
libvvp.so, that may be linked with other programs so that they can host
|
||||
a vvp simulation. ::
|
||||
|
||||
|
|
@ -111,31 +132,196 @@ a vvp simulation. ::
|
|||
|
||||
PLI version 1 (the ACC and TF routines) were deprecated in IEEE 1364-2005.
|
||||
These are supported in Icarus Verilog by the libveriuser library and cadpli
|
||||
module. Starting with v13, these will only be built if this option is used.
|
||||
module. Starting with V13, these will only be built if this option is used.
|
||||
|
||||
Compiling on Linux/Unix
|
||||
-----------------------
|
||||
|
||||
(Note: You will need to install bison, flex, g++ and gcc) This is probably the
|
||||
easiest case. Given that you have the source tree from the above instructions,
|
||||
the compile and install is generally as simple as::
|
||||
Note: For a gcc compile you will need to install ``bison``, ``flex``, ``g++``,
|
||||
``gcc`` and preferably `bz2`, `zlib` and `readline` development packages. The
|
||||
`bz2` and `zlib` development packages are required for the non-VCD waveform
|
||||
dumpers and the `readline` development package is needed to enable better
|
||||
terminal control in the ``vvp`` interactive mode.
|
||||
|
||||
% ./configure
|
||||
% make
|
||||
(su to root)
|
||||
# make install
|
||||
If you are only compiling one variant then you can compile directly in the
|
||||
source tree. If you need multiple variants (optimized, debugging, multiple
|
||||
compilers) then it is recommended you compile each in their own directory.
|
||||
|
||||
The "make install" typically needs to be done as root so that it can install
|
||||
in directories such as "/usr/local/bin" etc. You can change where you want to
|
||||
install by passing a prefix to the "configure" command::
|
||||
For multiple variants create a directory for each of the variants you intend
|
||||
to create and in each run the following steps, adjusting the options in the
|
||||
configure stage to get the functionality you want. For a single build you can
|
||||
either build it with the source or in a separate build directory.
|
||||
|
||||
% ./configure --prefix=/my/special/directory
|
||||
The following is from a Ubuntu 22.04 machine using gcc (version 11.4)::
|
||||
|
||||
This will configure the source for eventual installation in the directory that
|
||||
you specify. Note that "rpm" packages of binaries for Linux are typically
|
||||
configured with "--prefix=/usr" per the Linux File System Standard.
|
||||
% mkdir gcc
|
||||
% cd gcc
|
||||
or
|
||||
% cd iverilog
|
||||
|
||||
Make sure you have the latest version of flex otherwise you will get an error
|
||||
You can also use ``clang/clang++``. I usual build optimized version for
|
||||
normal use and reserve debugging options for a valgrind or a separate
|
||||
debugging build. Make sure you have `sudo` permission if you are using a
|
||||
system prefix area, otherwise you need to use some place you have
|
||||
permission to install (e.g. ~/).::
|
||||
|
||||
% env CFLAGS=-O2 CXXFLAGS=-O2 LDFLAGS=-s CC=gcc CXX=g++ ../iverilog/configure --enable-suffix=-gcc --prefix=/usr/local
|
||||
|
||||
This will generate the following (with some inline comments)::
|
||||
|
||||
checking build system type... x86_64-pc-linux-gnu
|
||||
checking host system type... x86_64-pc-linux-gnu
|
||||
checking for gcc... gcc
|
||||
checking whether the C compiler works... yes
|
||||
...
|
||||
checking for gperf... gperf # required for git builds
|
||||
checking for man... man # you likely want manual pages
|
||||
checking for ps2pdf... ps2pdf
|
||||
checking for groff... groff
|
||||
checking for git... git # required for git builds
|
||||
checking for flex... flex # required
|
||||
checking for bison... bison # required
|
||||
...
|
||||
checking for tputs in -ltermcap... yes
|
||||
checking for readline in -lreadline... yes
|
||||
checking for add_history in -lreadline... yes
|
||||
checking for readline/readline.h... yes
|
||||
checking for readline/history.h... yes # you likely want this
|
||||
...
|
||||
checking for pthread_create in -lpthread... yes
|
||||
checking for gzwrite in -lz... yes
|
||||
checking for gzwrite in -lz... (cached) yes
|
||||
checking for BZ2_bzdopen in -lbz2... yes
|
||||
checking for BZ2_bzdopen in -lbz2... (cached) yes # you want these for fst dumping
|
||||
...
|
||||
<Create all the parameterized Makefile and header files>
|
||||
|
||||
Usually if ``configure`` fails there is some required dependency missing. I
|
||||
usually review all the output to make sure it makes sense (e.g. I requested
|
||||
``gcc`` and that's what is being used, other things match my expectation). If
|
||||
all the waveform dumpers are not enabled there could be a few test failures.
|
||||
|
||||
Next we need to compile the code. Note: make sure you are using GNU make.
|
||||
It may be named gmake (e.g. GhostBSD)::
|
||||
|
||||
% make check >& make.log
|
||||
|
||||
This is for a tcsh/csh shell. Bash/fish/zsh use ``&>`` instead of ``>&``.
|
||||
Once this has completed check the make.log for any errors. There should not
|
||||
be any! I also check for warnings. There are often some related to the
|
||||
output from bison. For example::
|
||||
|
||||
From: ./parse.cc
|
||||
parse.cc:9462:18: warning: missing initializer for member ‘vlltype::lexical_pos’ [-Wmissing-field-initializers]
|
||||
9462 | = { 1, 1, 1, 1 }
|
||||
| ^
|
||||
parse.cc:9462:18: warning: missing initializer for member ‘vlltype::text’ [-Wmissing-field-initializers]
|
||||
|
||||
and::
|
||||
|
||||
From: ./vvp/parse.cc
|
||||
parse.cc:3242: warning: suspicious sequence in the output: m4_type [-Wother]
|
||||
parse.cc:3248: warning: suspicious sequence in the output: m4_type [-Wother]
|
||||
|
||||
Are common, but benign warnings. Different compilers or compiler versions may
|
||||
have other warnings.
|
||||
|
||||
The expected last few lines of the make.log file and these indicate everything
|
||||
should be working as expected are::
|
||||
|
||||
...
|
||||
driver/iverilog -B. -BMvpi -BPivlpp -tcheck -ocheck.vvp ../iverilog/examples/hello.vl
|
||||
vvp/vvp -M- -M./vpi ./check.vvp | grep 'Hello, World'
|
||||
Hello, World
|
||||
|
||||
If everything is good to this point and you are installing into a system
|
||||
prefix; install using ``sudo`` as shown below. If you are installing into a
|
||||
personal location skip the ``sudo``::
|
||||
|
||||
% sudo make install
|
||||
|
||||
Now you should verify the regression test suite is working as expected::
|
||||
|
||||
% cd ../iverilog/ivtest
|
||||
% ./vvp_reg.pl --suffix=-gcc
|
||||
|
||||
This is the original test script and should give no failures::
|
||||
|
||||
Running compiler/VVP tests for Icarus Verilog version: 13, suffix: -gcc.
|
||||
----------------------------------------------------------------------------
|
||||
macro_with_args: Passed.
|
||||
mcl1: Passed.
|
||||
pr622: Passed.
|
||||
pr639: Passed.
|
||||
...
|
||||
ssetclr2: Passed.
|
||||
ssetclr3: Passed.
|
||||
synth_if_no_else: Passed.
|
||||
ufuncsynth1: Passed.
|
||||
============================================================================
|
||||
Test results:
|
||||
Total=3018, Passed=3013, Failed=0, Not Implemented=2, Expected Fail=3
|
||||
|
||||
Next run the new test script::
|
||||
|
||||
% ./vvp_reg.py --suffix=-gcc
|
||||
|
||||
This should also give no failures::
|
||||
|
||||
Running compiler/VVP tests for Icarus Verilog version: 13, suffix: -gcc
|
||||
Using list(s): regress-vvp.list
|
||||
----------------------------------------------------------------------------
|
||||
always4A: Passed - CE.
|
||||
always4B: Passed - CE.
|
||||
analog1: Not Implemented.
|
||||
analog2: Not Implemented.
|
||||
...
|
||||
vvp_quiet_mode: Passed.
|
||||
warn_opt_sys_tf: Passed - EF.
|
||||
wreal: Passed.
|
||||
writemem-invalid: Passed - EF.
|
||||
============================================================================
|
||||
Test results: Ran 284, Failed 0.
|
||||
|
||||
Finally you can check that the VPI is working properly using::
|
||||
|
||||
% ./vpi_reg.pl --suffix=-gcc
|
||||
|
||||
The output for this should have no failures::
|
||||
|
||||
Running VPI tests for Icarus Verilog version: 13, suffix: -gcc.
|
||||
----------------------------------------------------------------------------
|
||||
br_gh59: Passed.
|
||||
br_gh73a: Passed.
|
||||
br_gh73b: Passed.
|
||||
br_gh117: Passed.
|
||||
...
|
||||
value_change_cb2: Passed.
|
||||
value_change_cb3: Passed.
|
||||
value_change_cb4: Passed.
|
||||
vpi_control: Passed.
|
||||
============================================================================
|
||||
Test results: Total=77, Passed=77, Failed=0, Not Implemented=0
|
||||
|
||||
You can uninstall everything using the following. If needed skip the ``sudo``
|
||||
as described in the install description above.::
|
||||
|
||||
% sudo make uninstall
|
||||
|
||||
You can cleanup the compile directory using::
|
||||
|
||||
% make clean
|
||||
or
|
||||
% make distclean
|
||||
|
||||
The first just cleans up just the compiled files, etc. The later cleans up
|
||||
the compiled file along with all the files generated in the ``configure``
|
||||
phase.
|
||||
|
||||
Note that "rpm" packages of binaries for Linux are typically configured with
|
||||
"--prefix=/usr" per the Linux File System Standard.
|
||||
|
||||
Make sure you have a recent version of flex otherwise you will get an error
|
||||
when parsing lexor.lex.
|
||||
|
||||
Compiling on Macintosh OS X
|
||||
|
|
@ -160,7 +346,13 @@ install icarus-verilog".
|
|||
Cross-Compiling for Windows
|
||||
---------------------------
|
||||
|
||||
These are instructions for building Icarus Verilog binaries for
|
||||
The `Cygwin` and `MSYS2` environments can compile Icarus Verilog as described
|
||||
above for `Linux/Unix`. There is a `MSYS2` build recipe which can be found in
|
||||
the `msys2/` directory. The accompanying README file provides further details.
|
||||
`MSYS2` is typically preferred over `Cygwin` since ``GTKWave`` and Icarus
|
||||
Verilog are both provided as pre-compiled packages.
|
||||
|
||||
What follows are older instructions for building Icarus Verilog binaries for
|
||||
Windows using mingw cross compiler tools on Linux.
|
||||
|
||||
To start with, you need the mingw64-cross-* packages for your linux
|
||||
|
|
@ -185,9 +377,3 @@ The configure generated the cross compiler flags, but there are a few
|
|||
bits that need to be compiled with the native compiler. (version.exe
|
||||
for example is used by the build process but is not installed.) The
|
||||
configure script should have gotten all that right.
|
||||
|
||||
Compiling for Windows using MSYS2
|
||||
---------------------------------
|
||||
|
||||
There is a MSYS2 build recipe which you can find under `msys2/` in the
|
||||
repository. The accompanying README file provides further details.
|
||||
|
|
|
|||
Loading…
Reference in New Issue