Add ADR for command-line option handling best practices#8758
Add ADR for command-line option handling best practices#8758tautschnig wants to merge 1 commit intodiffblue:developfrom
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #8758 +/- ##
===========================================
- Coverage 80.02% 80.01% -0.01%
===========================================
Files 1700 1700
Lines 188345 188345
Branches 73 73
===========================================
- Hits 150716 150702 -14
- Misses 37629 37643 +14 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
110b4ac to
affa974
Compare
affa974 to
20ffe00
Compare
There was a problem hiding this comment.
Pull request overview
Adds a new ADR that documents best practices and architecture for command-line option handling in CBMC, and links it from the ADR index.
Changes:
- Introduce an ADR covering philosophy, key data structures (
cmdlinet,optionst,configt), and a step-by-step guide for adding options - Document guidelines for help text, defaults, conflicts, deprecation, and testing
- Add the new ADR to the ADR README navigation
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| doc/ADR/command_line_option_handling.md | New ADR documenting CLI option handling patterns and recommendations |
| doc/ADR/README.md | Adds a link to the new command-line option handling ADR |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| #define CBMC_OPTIONS \ | ||
| OPT_BMC \ | ||
| "(no-standard-checks)" \ | ||
| "(my-new-option)" \ // Boolean flag | ||
| "(my-valued-option):" \ // Option requiring a value (note the colon) | ||
| OPT_FUNCTIONS \ | ||
| // ... rest of options |
There was a problem hiding this comment.
The macro example shows line-continuation backslashes followed by spaces and // comments. In C/C++, a \\ must be the last character on the line to continue a macro; showing it with trailing whitespace/comments is misleading and can cause copy/paste failures. Consider moving the comments to their own preceding lines (or using /* ... */ before the trailing \\) so the \\ is at end-of-line in the example.
| #define OPT_GOTO_CHECK \ | ||
| "(bounds-check)(pointer-check)(memory-leak-check)" \ | ||
| "(my-new-check)" // Add here \ | ||
| "(div-by-zero-check)" \ | ||
| // ... rest of options |
There was a problem hiding this comment.
Same issue as above: the macro continuation example mixes \\ line continuations with end-of-line // comments and alignment spacing. Since \\ must be the final character on the line, this example could lead to incorrect macros if copied. Adjust the formatting so comments don’t appear after a continuation, and keep each continuation backslash at true end-of-line.
| ## Command-Line Interface | ||
|
|
||
| * \subpage command-line-option-handling |
There was a problem hiding this comment.
The ADR index appears to use plain \\subpage ... entries (e.g., the existing \\subpage symex-ready-goto) rather than a Markdown bullet list. Consider matching the existing style (remove the * ) to keep the Doxygen/Markdown formatting consistent and avoid differences in rendered structure.
Add comprehensive documentation for command-line option handling best practices based on GitHub issue diffblue#1521. Includes philosophy, architecture, and step-by-step developer guide. Fixes: diffblue#1521
20ffe00 to
520964a
Compare
Add comprehensive documentation for command-line option handling best practices based on GitHub issue #1521. Includes philosophy, architecture, and step-by-step developer guide.
Fixes: #1521