96 lines
4.2 KiB
Org Mode
96 lines
4.2 KiB
Org Mode
#+title: Annotator - an interactive Coverity annotation tool
|
|
|
|
* Abstract
|
|
|
|
This tool lets you interactively annotate your code given a =defects.err= file. The file should contain file and line information along with the Coverity rule that was violated. An example may look like this:
|
|
|
|
#+begin_example csv
|
|
main.cpp:162:INFO: Newest, autosar_cpp14_a20_8_6_violation: Object "std::unique_ptr<Configuration const, std::default_delete<Configuration const> >(read_configuration(uri))" is not constructed using "std::make_shared".
|
|
#+end_example
|
|
|
|
* Installation
|
|
|
|
Get the most recent release, unpack it and add the binary to your PATH.
|
|
|
|
* Usage
|
|
|
|
After a /Coverity™/ run, you end up with a =defects.err= and would like to
|
|
annotate your code accordingly. In order to do so, just execute the =annotator=:
|
|
|
|
#+begin_src sh
|
|
annotator
|
|
#+end_src
|
|
|
|
This will by default use the =defects.err= file in the current directory and
|
|
scan it for violations. It will then ask you what to do with each violation - by
|
|
default only /Newest/ violations will be handled, but this can be overridden
|
|
with a command-line switch.
|
|
|
|
After all violations have been treated, you'll end up with a bunch of =*.fix=
|
|
files next to each source file - those are the annotated source files - you may
|
|
run diff on them to check if they look fine or just move them over your original
|
|
source file.
|
|
|
|
** Possible annotations
|
|
|
|
The annotator is able to generate three kinds of annotations:
|
|
|
|
- Intentional :: by pressing =i=, this will annotate with =coverity[rule] <reason>=
|
|
- FalsePositive :: by pressing =f=, this will annotate with =coverity[rule : FALSE] <reason>=
|
|
- Todo :: by pressing =t=, this will annotate with a TODO marker
|
|
|
|
* Advanced usage scenarios
|
|
|
|
The current annotator supports the following command-line arguments:
|
|
|
|
#+name: annotator-help
|
|
#+begin_src sh :results output :exports both
|
|
annotator --help
|
|
#+end_src
|
|
|
|
#+RESULTS: annotator-help
|
|
#+begin_example
|
|
Usage: annotator [OPTIONS] files...
|
|
|
|
A tool to semi-automatically add Coverity source-code annotations based on found defects.
|
|
|
|
|
|
-v --verbose be more verbose, pass multiple times to increase verbosity
|
|
-i --inplace replace source-file after inserting annotations
|
|
-V --version show full version information
|
|
--short-version show just the version number
|
|
-h --help show usage information
|
|
-b --batch run in batch mode, i.e. do not ask any questions
|
|
-a --all handle all defects not just Newest
|
|
-C[NUM] --context[=NUM] specify how much context should be shown around a violation
|
|
-t STRING --todo-marker=STRING override the default TODO marker with a custom string
|
|
-A FILE --annotations=FILE load automatic annotation rules
|
|
some examples:
|
|
Intentional (Rule "rule_1") "some reason"
|
|
FalsePositive (Rule "rule_1") "some reason"
|
|
ToDo (Rule "rule_1")
|
|
# a comment
|
|
-- another comment
|
|
#+end_example
|
|
|
|
** In-place annotations
|
|
|
|
The =annotator= allows to annotate in-place, i.e. it will automatically rename the =.fix= file after you are done with all violations within that file. This can be achieved by passing =-i= or =--inplace=.
|
|
|
|
** Process all violations
|
|
|
|
By default the annotator will only handle *Newest* violations and not those that are already contained within the Coverity database for some reason. However, it's still possible to process all found violations by passing =-a= or =--all= on the command-line.
|
|
|
|
** Insert annotations automatically
|
|
|
|
In case you have violations that always result in the same annotation over and over again, you can supply one or more files that contain automatic decisions.
|
|
|
|
Each line may be one of the following:
|
|
|
|
#+begin_example haskell
|
|
Intentional (Rule "autosar_cpp14_a18_9_1") "reason why it's intentional"
|
|
FalsePositive (Rule "autosar_cpp14_a18_9_1") "reason why it's a false-positive"
|
|
ToDo (Rule "autosar_cpp14_a18_9_1")
|
|
#+end_example
|
|
|
|
Lines may be disabled by prefixing them with =#= or =--=.
|