doc: Replace README.md by README.org
This commit is contained in:
Alexander Kobjolke
parent
f55a6c71b6
commit
737ff6afe3
3 changed files with 78 additions and 94 deletions
20
Makefile
20
Makefile
|
|
@ -1,22 +1,27 @@
|
|||
.PHONY: default all install watch clean build release distclean lint
|
||||
.PHONY: default all install watch clean build release distclean lint doc
|
||||
default: all
|
||||
|
||||
all: build
|
||||
|
||||
build: builddir build/bin/annotator
|
||||
|
||||
GHCFLAGS = -iapp -isrc -Wall -O2 -outputdir build/.obj
|
||||
BUILDDIR = build
|
||||
DESTDIR = ~/.local
|
||||
BINDIR = ${DESTDIR}/bin
|
||||
DOCDIR = ${DESTDIR}/share/doc/annotator
|
||||
|
||||
build: builddir | $(BUILDDIR)/bin/annotator doc
|
||||
|
||||
builddir:
|
||||
mkdir -p $(BUILDDIR)/bin $(BUILDDIR)/.obj $(BUILDDIR)/ci $(BUILDDIR)/dist
|
||||
mkdir -p $(BUILDDIR)/{bin,.obj,ci,dist,doc}
|
||||
|
||||
doc: builddir | $(BUILDDIR)/doc/README.md
|
||||
|
||||
$(BUILDDIR)/bin/annotator: app/Main.hs src/*.hs
|
||||
ghc --make $(GHCFLAGS) $< -o $@
|
||||
|
||||
$(BUILDDIR)/doc/README.md: README.org
|
||||
pandoc -t gfm $< -o $@
|
||||
|
||||
watch:
|
||||
@git ls-files src app Makefile | entr make -s build install
|
||||
|
||||
|
|
@ -31,9 +36,10 @@ clean:
|
|||
distclean: clean
|
||||
@rm -rf dist
|
||||
|
||||
install: $(BUILDDIR)/bin/annotator
|
||||
@install -m 0755 -D -t ${BINDIR} $<
|
||||
@install -m 0644 -D -t ${DOCDIR} README.md
|
||||
install: build
|
||||
@install -m 0755 -D -t ${BINDIR} $(BUILDDIR)/bin/annotator
|
||||
@install -m 0644 -D -t ${DOCDIR} README.org
|
||||
@install -m 0644 -D -t ${DOCDIR} $(BUILDDIR)/doc/README.md
|
||||
|
||||
release: script/make-release
|
||||
@$<
|
||||
|
|
|
|||
84
README.md
84
README.md
|
|
@ -1,84 +0,0 @@
|
|||
# Annotator - an interactive TM2/TM3 annotation tool
|
||||
|
||||
This tool lets you interactively annotate your code given a =defects.err= file.
|
||||
|
||||
## Installation
|
||||
|
||||
Get the most recent release, unpack it and add the binary to your PATH.
|
||||
|
||||
## How to use it
|
||||
|
||||
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=:
|
||||
|
||||
```
|
||||
annotator
|
||||
```
|
||||
|
||||
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>`
|
||||
- *False-Positive* - by pressing `f`, this will annotate with `coverity[rule : FALSE] <reason>`
|
||||
- *Todo* - by pressing `t`, this will annotate with a FIXME marker
|
||||
|
||||
## Advanced usage scenarios
|
||||
|
||||
The current annotator supports the following command-line arguments:
|
||||
|
||||
```
|
||||
$ annotator --help
|
||||
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
|
||||
-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
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```
|
||||
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")
|
||||
```
|
||||
|
||||
Lines may be disabled by prefixing them with `#` or `--`.
|
||||
68
README.org
68
README.org
|
|
@ -1,14 +1,54 @@
|
|||
#+title: Readme
|
||||
#+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
|
||||
|
||||
#+begin_src sh :results output
|
||||
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:
|
||||
#+RESULTS: annotator-help
|
||||
#+begin_example
|
||||
Usage: annotator [OPTIONS] files...
|
||||
|
||||
|
|
@ -32,3 +72,25 @@ A tool to semi-automatically add Coverity source-code annotations based on found
|
|||
# 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 =--=.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue