Developer Guide
From Icarus Verilog
This guide is intended to help you get started working with the Icarus Verilog source code, beyond simply compiling it. If all you want is to get and compile the code on your system, see the Installation Guide. But if you intend to work on the code, whether you intend to submit patches or not, this guide is for you.
There is a moderated mailing list for developers on sourceforge.net. This list is intended for discussion amongst the developers, hence the moderation. Although off-topic messages will be discarded (and that includes general usage support requests) questions about how to help yourself, or at least how to diagnose problems, are entertained.
If you are looking for project ideas, go to the Projects page.
Contents |
[edit] Getting Started with the Source Code
For development it is suggested to base changes on the current git repository. This will allow you to submit changes as a patch against the latest git version. Submitting patches relative the latest git saves everyone concerned a lot of headaches.
There is a section in the Installation Guide that explains how to check out the code from the main repository. It also explains how to prepare it to compile on the local system.
As the main repository is changed, you can update your copy with a simple "git pull". This combines the "git fetch" (fetch change sets from the remote repository) and "git merge" (merge those changes with your working branch.) This will automatically bring down just the changes from the upstream. That way, you always have access to the very latest version of the source.
When you are done with work of your own, make sure you commit your work into your local repository. Don't be afraid of this word, "commit". In git, "commit" only puts changes together into a change set. It is entirely local. To commit your changes, therefore:
% git add <files that have been changed> % git commit
Note that with git, all changes must be added, and not just new files. Use the "git status" and "git diff" commands to help figure out what those files are. Add those files with the "git add" command, then wrap the lot into a change set with the "git commit" command.
The commit will ask for a commit message. The convention for commit messages is to include two paragraphs: The first is a single line short description of what the change set is about, then after a blank line the second paragraph is a more verbose description of the patch.
To get the changes into the upstream, you need to submit a patch to the owner of the repository, who can push it in.
The command:
% git format-patch -o patches
puts together patches that you can submit for inclusion in the main repository. This command may produce a long run of patches (one for each change set) and it is common to want to make a patch for only the last change set. That can be managed with this command:
% git format-patch -o patches '@{1}'
This makes a patch for only the last change set in the current branch.
Of course, there is much more to git. This summary should be enough to get you started, especially if you are used to working with CVS, but for an understanding of the full power if git, see the various documentation resources on the 'net.
For a summary of the current conventions for the main git repository at icarus.com, see the GIT Branch Summary page.
[edit] Testing Your Work
There is a test suite created by Steve Wilson and maintained by the Icarus Verilog project at http://sourceforge.net/projects/ivtest.
Because the test suite is constantly growing, no effort is made to make release files. Instead, always use CVS to get the current test suite. The instructions for accessing CVS are available on the sourceforge help pages, but the short story is:
% cvs -d:pserver:anonymous@ivtest.cvs.sourceforge.net:/cvsroot/ivtest login
(For password hit ENTER)
% cvs -z3 -d:pserver:anonymous@ivtest.cvs.sourceforge.net:/cvsroot/ivtest co -P testsuite
The test suite contains a large number of regression tests, as well as scripts to run the tests, and files that show the expected results for various branches and the current devel version of Icarus Verilog.
The main script to run the test suite is "vvp_reg.pl". Yes, it is a Perl script. This assumes that the iverilog and vvp programs you want to test are in your path.
The regression_reports-v0.8.txt file is the expected results for the v0.8 branch of Icarus Verilog. After you run the vvp_reg.pl program, you will get the output file "regression_report.txt" that you can compare with the "regression_report-v0.8.txt" file to see where there are differences.
Similarly, the "regression_report-devel.txt" file is the expected results for the current development. The file is tagged with Icarus Verilog snapshot names so that you can get historical results as well.
It is recommended that after you make changes to Icarus Verilog, you rerun the regression test suite to check that you didn't break something else. The compiler is a very complicated thing and regressions are easy to trip over.
It is also highy recommended that you create regression tests of your own to test the results of your own work. These tests can go into the regression test suite so that others who edit the compiler can be sure they are not breaking your code in the process.
[edit] Submitting Patches
You should be using a local git repository to develop your patch, so the proper way to submit a patch is to format it by committing your work to your local repository using:
% git commit
In your commit message, include a short 1-line summary, then a blank line, then a description of the purpose of the patch. The "git commit" command doesn't enforce this format, but the visualizing tools assume it when making pretty displays of the tree of patches.
Once your work is committed to your local repository, you can format the patch with the command:
% git format-patch '@{1}'
This will format your last commit into a git-style patch that you can submit to the Icarus Verilog Patches tracker.
The patch you submit is handled by a developer who applies the patch you submit with the command:
% git am <your-patch-file>
to an integration repository. It is tested, then pushed into the main repository. When the patch is applied to the main repository, you then use the command:
% git pull
to merge. You will be able to then use
% gitk
to see your patch in the main branch that you are tracking.
When you become more expert with using git, then you can in principle do a bunch of changes in a bunch of commits and submit them as a set of patches at a later time.
[edit] Choosing a Task
The task you choose is entirely up to you. Some thought through suggestions can be found in the Projects page.
