Getting Started as a Contributor
********************************

Icarus Verilog development is centered around the github repository at
github.com/steveicarus/iverilog. Contributing to Icarus Verilog
requires a basic knowledge of git and github, so see the github
documentation for more information. The sections below will step you
through the basics of getting the source code from github, making a
branch, and submitting a pull request for review.


Getting Icarus Verilog
======================

To start, you will need to clone the code. It is preferred that you
use the "ssh" method, and the ssh based clone with the command:

   % git clone git@github.com:steveicarus/iverilog.git

This assumes that you have a github account (accounts are free) and
you have set up your ssh authentication keys. See the Authentication
Guides here.

The "git clone" command will get you all the source:

   % git clone git@github.com:steveicarus/iverilog.git
   Cloning into 'iverilog'...
   remote: Enumerating objects: 66234, done.
   remote: Counting objects: 100% (6472/6472), done.
   remote: Compressing objects: 100% (4123/4123), done.
   remote: Total 66234 (delta 2412), reused 6039 (delta 2190), pack-reused 59762
   Receiving objects: 100% (66234/66234), 27.98 MiB | 2.53 MiB/s, done.
   Resolving deltas: 100% (50234/50234), done.
   % 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 tracks the development head. However, If you want to actually be
working on a specific version, say for example version 11, the
v11-branch, you checkout that branch with the command:

   % git checkout --track -b v11-branch origin/v11-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 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 push/pull from the remote repository.

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:

   % git pull
   Already up to date.

Finally, configuration files are built by the extra step:

   % sh autoconf.sh
   Autoconf in root...
   Precompiling lexor_keyword.gperf
   Precompiling vhdlpp/lexor_keyword.gperf

You will need autoconf and gperf installed in order for the script to
work. If you get errors such as:

   % sh autoconf.sh
   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.

Now you are ready to configure and compile the source.


Icarus Specific Configuration Options
=====================================

Icarus takes many of the standard configuration options and those will
not be described here. The following are specific to Icarus Verilog:

   --enable-suffix[=suffix]

This option allows the user to build Icarus with a default suffix or
when provided a user defined suffix. 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).

   --enable-libvvp

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.

   --enable-libveriuser

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.

A debug options is:

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


Compiling on Linux
==================

(Note: You will need to install bison, flex, g++ and gcc) This is
probably the easiest step. Given that you have the source tree from
the above instructions, the compile and install is generally as simple
as:

   % ./configure
   configure: loading site script /usr/share/site/x86_64-unknown-linux-gnu
   checking build system type... x86_64-unknown-linux-gnu
   checking host system type... x86_64-unknown-linux-gnu
   checking for gcc... gcc
   checking whether the C compiler works... yes
   checking for C compiler default output file name... a.out
   checking for suffix of executables...
   [...and so on...]

   % make
   mkdir dep
   Using git-describe for VERSION_TAG
   g++ -DHAVE_CONFIG_H -I. -Ilibmisc  -Wall -Wextra -Wshadow   -g -O2 -MD -c main.cc -o main.o
   mv main.d dep/main.d
   g++ -DHAVE_CONFIG_H -I. -Ilibmisc  -Wall -Wextra -Wshadow   -g -O2 -MD -c async.cc -o async.o
   mv async.d dep/async.d
   g++ -DHAVE_CONFIG_H -I. -Ilibmisc  -Wall -Wextra -Wshadow   -g -O2 -MD -c design_dump.cc -o design_dump.o
   mv design_dump.d dep/design_dump.d
   g++ -DHAVE_CONFIG_H -I. -Ilibmisc  -Wall -Wextra -Wshadow   -g -O2 -MD -c discipline.cc -o discipline.o
   [...and so on...]

The end result is a complete build of Icarus Verilog. You can install
your compiled version with a command like this:

   % sudo make install


Regression Tests
================

Icarus Verilog comes with a fairly extensive regression test suite. As
of 2022, that test suite is included with the source in the "ivtest"
directory. Contained in that directory are a couple driver scripts
that run all the regression tests on the installed version of Icarus
Verilog. So for example:

   % cd ivtest
   % ./vvp_reg.pl
   % ./vvp_reg.py
   % ./vpi_reg.pl

will run all the regression tests for the simulation engine. (This is
what most people will want to do.) You should rerun these tests before
submitting patches to the developers. Also, if you are adding a new
feature, you should add test programs to the regression test suite to
validate your new feature (or bug fix.). The python script is the
preferred method to add new tests.

All of these scripts take other options to test various
configurations. What options are supported can be found by using the
"-h/--help" argument. There is also a separate "vlog95_reg.pl" script
for testing the vlog95 translation of the original tests. This is
integrated into the existing Python test script for the new tests.

Note that pull requests will be required to pass these regression
tests before being merged.


Forks, Branches and Pull Requests
=================================

Currently, the preferred way to submit patches to Icarus Verilog is
via pull requests. Pull requests can be created from the main
repository if you have write access (very few people have write
access) or more commonly from a fork, so the first step is to create a
fork that you can work with. It is easy enough to create a fork, just
go to the github.com/steveicarus/iverilog page and use the "fork"
button in the upper right corner. This will create a new repository
that you can clone instead of the steveicarus/iverilog repository. You
then use your local repository to create feature branches, then submit
them for inclusion in the main repository as pull requests. Remember
to synchronize your fork periodically with the main repository. This
will make sure your work is based on the latest upstream and avoid
merge conflicts.

Create your patch by first creating a branch that contains your
commits:

   % git checkout -b my-github-id/branch-name

We are encouraging using this scheme for naming your branches that are
destined for pull requests. Use your github id in the branch name. So
for example:

   % git checkout -b steveicarus/foo-feature

Do your work in this branch, then when you are ready to create a pull
request, first push the branch up to github:

   % git push -u origin my-github-id/branch-name

Then go to github.com to create your pull request. Create your pull
request against the "master" branch of the upstream repository, or the
version branch that you are working on. Your pull request will be run
through continuous integration, and reviewed by one of the main
authors. Feedback may be offered to your PR, and once accepted, an
approved individual will merge it for you. Then you are done.
