luke
/
iverilog
mirror of https://github.com/steveicarus/iverilog.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
iverilog/developer/getting_started.html

311 lines
17 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Getting Started as a Contributor &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=cb25574f" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=888ff710"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="The Regression Test Suite" href="regression_tests.html" />
<link rel="prev" title="Icarus Verilog Developer Support" href="index.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="getting-started-as-a-contributor">
<h1>Getting Started as a Contributor<a class="headerlink" href="#getting-started-as-a-contributor" title="Link to this heading"></a></h1>
<p>Icarus Verilog development is centered around the github repository at
<a class="reference external" href="http://github.com/steveicarus/iverilog">github.com/steveicarus/iverilog</a>.
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.</p>
<section id="getting-icarus-verilog">
<h2>Getting Icarus Verilog<a class="headerlink" href="#getting-icarus-verilog" title="Link to this heading"></a></h2>
<p>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:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>clone<span class="w"> </span>git@github.com:steveicarus/iverilog.git
</pre></div>
</div>
<p>This assumes that you have a github account (accounts are free) and you have
set up your ssh authentication keys. See the
<a class="reference external" href="https://docs.github.com/en/authentication">Authentication Guides here</a>.</p>
<p>The “git clone” command will get you all the source:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>clone<span class="w"> </span>git@github.com:steveicarus/iverilog.git
<span class="go">Cloning into &#39;iverilog&#39;...</span>
<span class="go">remote: Enumerating objects: 66234, done.</span>
<span class="go">remote: Counting objects: 100% (6472/6472), done.</span>
<span class="go">remote: Compressing objects: 100% (4123/4123), done.</span>
<span class="go">remote: Total 66234 (delta 2412), reused 6039 (delta 2190), pack-reused 59762</span>
<span class="go">Receiving objects: 100% (66234/66234), 27.98 MiB | 2.53 MiB/s, done.</span>
<span class="go">Resolving deltas: 100% (50234/50234), done.</span>
<span class="gp">% </span><span class="nb">cd</span><span class="w"> </span>iverilog/
</pre></div>
</div>
<p>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:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>checkout<span class="w"> </span>--track<span class="w"> </span>-b<span class="w"> </span>v11-branch<span class="w"> </span>origin/v11-branch
</pre></div>
</div>
<p>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.</p>
<p>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:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>pull
<span class="go">Already up to date.</span>
</pre></div>
</div>
<p>Finally, configuration files are built by the extra step:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>sh<span class="w"> </span>autoconf.sh
<span class="go">Autoconf in root...</span>
<span class="go">Precompiling lexor_keyword.gperf</span>
<span class="go">Precompiling vhdlpp/lexor_keyword.gperf</span>
</pre></div>
</div>
<p>You will need autoconf and gperf installed in order for the script to work.
If you get errors such as:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>sh<span class="w"> </span>autoconf.sh
<span class="go">Autoconf in root...</span>
<span class="go">autoconf.sh: 10: autoconf: not found</span>
<span class="go">Precompiling lexor_keyword.gperf</span>
<span class="go">autoconf.sh: 13: gperf: not found.</span>
</pre></div>
</div>
<p>You will need to install download and install the autoconf and gperf tools.</p>
<p>Now you are ready to configure and compile the source.</p>
</section>
<section id="icarus-specific-configuration-options">
<h2>Icarus Specific Configuration Options<a class="headerlink" href="#icarus-specific-configuration-options" title="Link to this heading"></a></h2>
<p>Icarus takes many of the standard configuration options and those will not be
described here. The following are specific to Icarus Verilog:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>--enable-suffix[=suffix]
</pre></div>
</div>
<p>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).</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>--enable-libvvp
</pre></div>
</div>
<p>The vvp progam 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.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>--enable-libveriuser
</pre></div>
</div>
<p>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.</p>
<p>A debug options is:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>--with-valgrind
</pre></div>
</div>
<p>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.</p>
</section>
<section id="compiling-on-linux">
<h2>Compiling on Linux<a class="headerlink" href="#compiling-on-linux" title="Link to this heading"></a></h2>
<p>(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:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>./configure
<span class="go">configure: loading site script /usr/share/site/x86_64-unknown-linux-gnu</span>
<span class="go">checking build system type... x86_64-unknown-linux-gnu</span>
<span class="go">checking host system type... x86_64-unknown-linux-gnu</span>
<span class="go">checking for gcc... gcc</span>
<span class="go">checking whether the C compiler works... yes</span>
<span class="go">checking for C compiler default output file name... a.out</span>
<span class="go">checking for suffix of executables...</span>
<span class="go">[...and so on...]</span>
<span class="gp">% </span>make
<span class="go">mkdir dep</span>
<span class="go">Using git-describe for VERSION_TAG</span>
<span class="go">g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c main.cc -o main.o</span>
<span class="go">mv main.d dep/main.d</span>
<span class="go">g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c async.cc -o async.o</span>
<span class="go">mv async.d dep/async.d</span>
<span class="go">g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c design_dump.cc -o design_dump.o</span>
<span class="go">mv design_dump.d dep/design_dump.d</span>
<span class="go">g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c discipline.cc -o discipline.o</span>
<span class="go">[...and so on...]</span>
</pre></div>
</div>
<p>The end result is a complete build of Icarus Verilog. You can install your
compiled version with a command like this:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>sudo<span class="w"> </span>make<span class="w"> </span>install
</pre></div>
</div>
</section>
<section id="regression-tests">
<h2>Regression Tests<a class="headerlink" href="#regression-tests" title="Link to this heading"></a></h2>
<p>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:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span><span class="nb">cd</span><span class="w"> </span>ivtest
<span class="gp">% </span>./vvp_reg.pl<span class="w"> </span>--strict
</pre></div>
</div>
<p>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.)</p>
<p>Note that pull requests will be required to pass these regression tests before
being merged.</p>
</section>
<section id="forks-branches-and-pull-requests">
<h2>Forks, Branches and Pull Requests<a class="headerlink" href="#forks-branches-and-pull-requests" title="Link to this heading"></a></h2>
<p>Currently, the preferred way to submit patches to Icarus Verilog is via pull
requests.
<a class="reference external" href="https://docs.github.com/en/github-ae&#64;latest/pull-requests">Pull requests</a>
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
<a class="reference external" href="http://github.com/steveicarus/iverilog">github.com/steveicarus/iverilog</a>
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 <a class="reference external" href="https://docs.github.com/en/github-ae&#64;latest/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork">synchronize your fork</a>
periodically with the main repository. This will make sure your work is based
on the latest upstream and avoid merge conflicts.</p>
<p>Create your patch by first creating a branch that contains your commits:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>checkout<span class="w"> </span>-b<span class="w"> </span>my-github-id/branch-name
</pre></div>
</div>
<p>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:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>checkout<span class="w"> </span>-b<span class="w"> </span>steveicarus/foo-feature
</pre></div>
</div>
<p>Do your work in this branch, then when you are ready to create a pull request,
first push the branch up to github:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>push<span class="w"> </span>-u<span class="w"> </span>origin<span class="w"> </span>my-github-id/branch-name
</pre></div>
</div>
<p>Then go to github.com to create your pull request. <a class="reference external" href="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">Create your pull request
against the “master” branch of the upstream repository</a>,
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.</p>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2"><a class="reference internal" href="guide/index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../index.html">Documentation overview</a><ul>
<li><a href="index.html">Icarus Verilog Developer Support</a><ul>
<li>Previous: <a href="index.html" title="previous chapter">Icarus Verilog Developer Support</a></li>
<li>Next: <a href="regression_tests.html" title="next chapter">The Regression Test Suite</a></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../_sources/developer/getting_started.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink