From 42d591d2966fbfabb1cf4d1c65d035493a0591ef Mon Sep 17 00:00:00 2001 From: Cary R Date: Sun, 1 Mar 2026 14:40:31 -0800 Subject: [PATCH] Update install docs and remove a doc build warning --- Documentation/conf.py | 3 +- Documentation/usage/installation.rst | 292 ++++++++++++++++++++++----- 2 files changed, 241 insertions(+), 54 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 36e31b654..32ef3a626 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -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. diff --git a/Documentation/usage/installation.rst b/Documentation/usage/installation.rst index 4eda8aedc..090f020f0 100644 --- a/Documentation/usage/installation.rst +++ b/Documentation/usage/installation.rst @@ -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 + ... + + +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.