226 lines
8.3 KiB
ReStructuredText
226 lines
8.3 KiB
ReStructuredText
|
|
Getting Started as a Contributor
|
|
================================
|
|
|
|
Icarus Verilog development is centered around the github repository at
|
|
`github.com/steveicarus/iverilog <http://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:
|
|
|
|
.. code-block:: console
|
|
|
|
% 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 <https://docs.github.com/en/authentication>`_.
|
|
|
|
The "git clone" command will get you all the source:
|
|
|
|
.. code-block:: console
|
|
|
|
% 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:
|
|
|
|
.. code-block:: console
|
|
|
|
% 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:
|
|
|
|
.. code-block:: console
|
|
|
|
% git pull
|
|
Already up to date.
|
|
|
|
Finally, configuration files are built by the extra step:
|
|
|
|
.. code-block:: console
|
|
|
|
% 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:
|
|
|
|
.. code-block:: console
|
|
|
|
% 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:
|
|
|
|
.. code-block:: none
|
|
|
|
--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).
|
|
|
|
A debug options is:
|
|
|
|
.. code-block:: none
|
|
|
|
--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
|
|
need 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:
|
|
|
|
.. code-block:: console
|
|
|
|
% ./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:
|
|
|
|
.. code-block:: console
|
|
|
|
% 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:
|
|
|
|
.. code-block:: console
|
|
|
|
% cd ivtest
|
|
% ./vvp_reg.pl --strict
|
|
|
|
will run all the regression tests for the simulation engine. (This is what
|
|
most people will want to do.) You should rerun this test 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.)
|
|
|
|
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 <https://docs.github.com/en/github-ae@latest/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 <http://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
|
|
<https://docs.github.com/en/github-ae@latest/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-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:
|
|
|
|
.. code-block:: console
|
|
|
|
% 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:
|
|
|
|
.. code-block:: console
|
|
|
|
% 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:
|
|
|
|
.. code-block:: console
|
|
|
|
% 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
|
|
<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_,
|
|
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.
|
|
|