From 3166973f59913408b1202c69225ad43db2af781b Mon Sep 17 00:00:00 2001 From: Stephen Williams Date: Fri, 15 Apr 2022 17:35:06 -0700 Subject: [PATCH] Document getting started as a developer --- .github/workflows/test.yml | 6 +- Documentation/developer/getting_started.rst | 225 ++++++++++++++++++++ Documentation/developer/index.rst | 1 + Documentation/usage/index.rst | 1 + Documentation/usage/reporting_issues.rst | 37 ++++ 5 files changed, 269 insertions(+), 1 deletion(-) create mode 100644 Documentation/developer/getting_started.rst create mode 100644 Documentation/usage/reporting_issues.rst diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index a1e86148d..480b33166 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -56,7 +56,7 @@ jobs: - name: Install dependencies run: | sudo apt update -qq - sudo apt install -y make g++ git bison flex gperf libreadline-dev autoconf + sudo apt install -y make g++ git bison flex gperf libreadline-dev autoconf python3-sphinx - name: Build, check and install run: | @@ -68,6 +68,10 @@ jobs: - name: Test run: ./.github/test.sh + - name: Documentation + run: | + cd Documentation + make html win: runs-on: windows-latest diff --git a/Documentation/developer/getting_started.rst b/Documentation/developer/getting_started.rst new file mode 100644 index 000000000..b0a231660 --- /dev/null +++ b/Documentation/developer/getting_started.rst @@ -0,0 +1,225 @@ + +Getting Started as a Contributer +================================ + +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: + +.. 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 `_. + +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 `_ +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: + +.. 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 +`_, +or the version branch that you are working on. Your pull reuqest 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. + diff --git a/Documentation/developer/index.rst b/Documentation/developer/index.rst index a30d2b7ff..3be5a5337 100644 --- a/Documentation/developer/index.rst +++ b/Documentation/developer/index.rst @@ -8,5 +8,6 @@ Icarus Verilog. .. toctree:: :maxdepth: 1 + getting_started version_stamps diff --git a/Documentation/usage/index.rst b/Documentation/usage/index.rst index cd6eabc55..7aa16ec38 100644 --- a/Documentation/usage/index.rst +++ b/Documentation/usage/index.rst @@ -17,3 +17,4 @@ Icarus Verilog. vvp_flags vpi ivl_target + reporting_issues diff --git a/Documentation/usage/reporting_issues.rst b/Documentation/usage/reporting_issues.rst new file mode 100644 index 000000000..1a5922b55 --- /dev/null +++ b/Documentation/usage/reporting_issues.rst @@ -0,0 +1,37 @@ + +Reporting Issues +================ + +The developers of and contributers to Icarus Verilog use github to track +issues and to create patches for the product. If you believe you have found a +problem, use the Issues tracker at the +`Icarus Verilog github page `_. + +On the main page, you will find a row of selections near the top. Click the +`Issues `_ link to get to the +list of issues, open and closed. You will find a friendly green button where +you can create a new issue. You will be asked to create a title for your +issue, and to write a detailed description of your issue. Please include +enough information that anyone who sees your issue can understand and +reproduce it. + +One key characteristic of a well reported issue is a small sample program that +demonstrates the issue. The smaller the better. No developer wants to wade +through hundreds of lines of working Verilog to find the few lines that cause +trouble, so if you can get it down to a 10 line sample program, then your +issue will be far more likely to be addressed. + +Be prepared to have a conversation about your issue. More often then you would +expect, the issue turns out to be a bug in your program, and the person +looking into your issue may point out a bug in your code. You learn something, +and we all win. We are not always correct, though, so if we are incorrect, +help us see our error, if that's appropriate. If we don't understand what your +issue is, we will label your issue with a "Need info" label, and if we never +hear from you again, your issue may be closed summarily. + +If you can submit a complete, working program that we can use in the +regression test suite, then that is the best. Check out the existing tests in +the regression test suite to see how they are structured. If you have a +complete test that can go into the test suite, then that saves everyone a lot +of grief, and again you increase the odds that your issue will be addressed. +