Docs: Add bugpoint guide #5139
Open
Docs: Add bugpoint guide #5139
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
How to guide for using bugpoint, minimizing yosys scripts, and minimizing verilog code. AKA how to MVCE.
Talk about input files coming from command line, the `read` command, and features provided by `RTLIL::Frontend` (making note that `read_slang` is a subclass but `ghdl` isn't).
Also dropping the `autosectionlabel_maxdepth = 1` so that I can actually use the auto section labels. Adds warning on bash substitution on scripting intro page when talking about `yosys -p`.
Fix error on duplicated heading. Drop `cmd_ref`_ link (everything already uses :doc:`cmd_ref`).
Add a note on fuzzers, with a polite suggestion that if you're fuzzing you should put in the work of identifying the underlying issue so that you (and we) are confident you're not raising multiple issues for the same bug.
Was previously in yosys_internals which is more developer focused, rather than user focused.
Also some other tidy up and clarifications.
What do I do with the minimized design and (the first half of) Minimizing scripts
More info for creating GitHub issues and the different sections. Discuss additional details that can be included as comments on the issue. Also mention Gists for large files (preferable to downloading a .txt). Add a warning about external plugins/tools. Also add a note to `load_design.rst` about `Frontend`s and `-f` command line option.
I just missed that it only gets included in the makefile if `DISABLE_SPAWN` is set, because I was looking for the C define `YOSYS_DISABLE_SPAWN`.
part 2: electric boogaloo
Move `yosys -h bugpoint` failure into a code-block to break up text. Same for the `exec -expect-return` example. TODOs on #5068 being merged.
Move the "creating an issue" section from bugpoint.rst to "reporting bugs" in `contributing.rst`. Fix link to `CONTRIBUTING.md`. Update `CONTRIBUTING.md` to refer to the bugpoint guide instead of the stack overflow guide.
Minimizing scripts (and more generally identifying root cause) isn't necessary for regular bug reports. Rather, it can be useful for developers working on *fixing* bugs, and also for fuzzers to avoid spam. Minor adjustments to `bugpoint.rst`. Add note to `advanced_bugpoint.rst` about primitives when minimizing scripts.
Update text to assume bugpoint PR changes.
| as Stack Overflow's `How to create a Minimal, Reproducible Example`_. | ||
|
|
||
| Unlike RTLIL designs where we can use `bugpoint`, minimizing Verilog designs is | ||
| a much more manual, iterative process. Be sure to check any errors or warnings |
There was a problem hiding this comment.
There are automated tools we can recommend here that are probably easier to use than manual reduction, most notably sv-bugpoint for (system)verilog and creduce with the --not-c flag that can be useful on a range of languages, including yosys scripts themselves.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What are the reasons/motivation for this change?
While
bugpointis great for minimising designs there isn't much documentation on how to do that.Explain how this is achieved.
Add a how-to guide on using
bugpoint, specifically aimed at people trying to minimise failing designs whether that failure is due to Yosys or the design. This includes both a user-facing guide for minimising designs and a more developer focused guide which goes into minimising scripts (with the suggestion that people using fuzzers to find bugs should be minimising their scripts so as to avoid duplicate issues).This also makes some additions to the Loading a design page and the contributing page which I totally forgot about until just now so they are still bullet points (though both pages already were mostly bullet points, this just adds more bullet points).
If applicable, please suggest to reviewers how they can test the change.
Check links above for preview build. Some of the content assumes changes from #5068 are included.