Implement documentation roadmap and fix no-op asserts in examples#818
Open
shaobo-he wants to merge 3 commits into
Open
Implement documentation roadmap and fix no-op asserts in examples#818shaobo-he wants to merge 3 commits into
shaobo-he wants to merge 3 commits into
Conversation
Following the documentation outline in #567, flesh out docs/running.md with new sections on understanding SMACK's output and counterexample traces, checking memory safety and integer overflow, verifying multi-file and whole-program bitcode, and selecting the verification back-end and solver. Every command and output shown was verified against a real SMACK run. While documenting assertions, discovered that assert() requires including <assert.h> (SMACK ships its own that routes assert to the verifier). The examples/simple and examples/simple-project programs omitted it, so their assertions were silently ignored (injecting assert(0) still reported "no errors"). Add the include to both examples and document the requirement, including the "implicit declaration of function 'assert'" pitfall. Also drop the now-obsolete whole-program-llvm reference and remove the stale "experimental unbounded verification" claim from the README. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
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.
Summary
Implements the documentation roadmap in #828 by consolidating and expanding
SMACK's user guidance in the repository, updated and checked against the current
command-line interface and verifier behavior.
Closes #828.
What changed
User documentation
docs/running.mdinto an entry-level guide covering assertions,assumptions, nondeterministic inputs, result interpretation, property checks,
multi-file programs, prelinked bitcode, and back-end selection.
docs/command-line-options.mdas a task-oriented guide to the optionsusers most commonly need.
docs/build-workflows.mdfor source, multi-file, saved-artifact,prelinked-bitcode, and Makefile workflows.
docs/advanced.mdfor modeling, experimental contracts, inline Boogie,uninterpreted functions, initialization hooks, and trace annotations.
docs/troubleshooting.mdfor common assertion, modeling, memory,toolchain, timeout, and generated-artifact problems.
legacy misspelled
loops-and-recusive-functionsblog anchor.Correctness clarifications
--checklist replaces the defaultassertionsproperty; examples select
assertionsexplicitly when combining checks.--unroll 4and clarified that--fail-on-loop-exitreports reachable normal exits, not paths truncated bybound exhaustion.
model-relative, including limitations of approximate integer, bitwise, and
floating-point encodings.
valid-freesemantics, and the scope of
--checked-functions(including the sharedvalid-freemodel exception).return-value limitation.
Examples and LLVM workflows
<assert.h>to the introductory C examples so their assertions aretranslated into verifier assertions rather than unresolved function calls.
for this checkout (
clang-14andllvm-link-14).-fsanitize=signed-integer-overflow,shiftbefore SMACK can check integeroverflow; selecting the property after compilation is too late.
examples/simple-project/Makefileto use the matching LLVM tools,preserve analyzable
-O0IR, and include overflow instrumentation.No production verifier implementation is changed; the non-documentation edits
are limited to the two example includes and the example Makefile.
Testing
git diff --checkbalanced code fences.
--checkreplacement and combined-property behavior.--fail-on-loop-exitreports the injected normal-exit check at bound 4.instrumentation and reports it after compilation with
-fsanitize=signed-integer-overflow,shift.clang-14/llvm-link-14and verifiedthe resulting bitcode with assertion and overflow checks enabled.
--checked-functionsexamples.