Commit dc95075e authored by Anton Ertl's avatar Anton Ertl

Refined documentation, especially for Coverage

parent 90a9841f
......@@ -29,7 +29,7 @@ cover-end Constant cover-start
[IFUNDEF] coverage?
0 Value coverage? ( -- flag ) \ gforth-exp
\G Coverage check on/off
\G Coverage check on/off.
[THEN]
0 value dead-cov?
......@@ -41,7 +41,7 @@ cover-end Constant cover-start
false to dead-cov? ;
: cov+ ( -- ) \ gforth-exp
\G add a coverage tag here
\G Add a coverage tag here.
dead-cov? 0= state @ and IF cov+, THEN
false to dead-cov? ; immediate compile-only
: ?cov+ ( flag -- flag ) \ gforth-exp
......@@ -55,14 +55,15 @@ cover-end Constant cover-start
:noname defers before-line postpone cov+ ; is before-line
: cov% ( -- ) \ gforth-exp
\G print the coverage percentage
\G Print the percentage of basic blocks loaded after
\G @file{coverage.fs} that are executed at least once.
0 cover-end cover-start U+DO
I cell+ @ 0<> -
2 cells +LOOP #2000 cells cover-end cover-start - */
0 <# '%' hold # '.' hold #s #> type ." coverage" ;
: .cover-raw ( -- ) \ gforth-exp
\G print all raw coverage data
\G Print raw execution counts.
cover-end cover-start U+DO
I @ .sourceview ." : " I cell+ ? cr
2 cells +LOOP ;
......@@ -75,13 +76,13 @@ Defer .cov#
: .paren-cov# ( n -- ) ." ( " 0 .r ." ) " ;
: color-cover ( -- ) ['] .ansi-cov# is .cov# ;
\G print coverage with colors
\G Print execution counts in colours (default).
: bw-cover ( -- ) ['] .paren-cov# is .cov# ;
\G print coverage with parents (source-code compatible)
\G Print execution counts in parentheses (source-code compatible).
color-cover
: ?del-cover ( addr u -- n )
\G remove coverage comment
\G Remove coverage comment.
2dup s" ( " string-prefix? IF
3 dup >r /string
BEGIN over c@ digit? WHILE drop 1 /string r> 1+ >r REPEAT
......@@ -89,7 +90,7 @@ color-cover
ELSE 2drop 0 THEN ;
: .cover-file { fn -- } \ gforth-exp
\G pretty print coverage in a file
\G Print coverage in included file with index @var{fn}.
fn included-buffer 0 locate-line 0 { d: buf lpos d: line cpos }
cover-end cover-start U+DO
I @ view>filename# fn = IF
......@@ -107,13 +108,13 @@ color-cover
line cpos safe/string type cr default-color attr! buf type ;
: covered? ( fn -- flag ) \ gforth-exp
\G check if file number @var{fn} has coverage information
\G Check if included file with index @var{fn} has coverage information.
false cover-end cover-start U+DO
over I @ view>filename# = or
2 cells +LOOP nip ;
: .coverage ( -- ) \ gforth-exp
\G pretty print coverage
\G Show code with execution frequencies.
cr included-files $[]# 0 ?DO
I covered? IF
I [: included-files $[]@ type ':' emit cr ;]
......@@ -123,7 +124,10 @@ color-cover
LOOP ;
: annotate-cov ( -- ) \ gforth-exp
\G annotate files with coverage information
\G For every file with coverage information, produce a @code{.cov}
\G file that has the execution frequencies inserted. We recommend
\G to use @code{bw-cover} first (with the default
\G @code{color-cover} you get escape sequences in the files).
included-files $[]# 0 ?DO
I covered? IF
I [: included-files $[]@ type ." .cov" ;] $tmp
......@@ -155,13 +159,13 @@ $10 buffer: cover-hash
['] $tmp $10 base-execute ;
: save-cov ( -- ) \ gforth-exp
\G save coverage counters
\G Save coverage counters.
cover-filename r/w create-file throw >r
cover-start cover-end over - r@ write-file throw
r> close-file throw ;
: load-cov ( -- ) \ gforth-exp
\G load coverage counters
\G Load coverage counters.
cover-filename r/o open-file dup #-514 = IF
2drop true [: ." no saved coverage found" cr ;] ?warning
EXIT THEN throw >r
......
......@@ -74,8 +74,8 @@ interpret/compile: ~~ ( -- ) \ gforth tilde-tilde
\ code coverage helpers that are always present
0 Value coverage?
\G Coverage check on/off
0 Value coverage? ( -- f )
\G Value: Coverage check on/off
$10 stack: cov-stack
: nocov[ ( -- )
......
......@@ -158,10 +158,10 @@ Gforth Environment
* Invoking Gforth:: Getting in
* Leaving Gforth:: Getting out
* Help on Gforth:: Getting help
* Command-line editing::
* Command-line editing:: Gforth's command-line editor
* Environment variables:: that affect how Gforth starts up
* Gforth Files:: What gets installed and where
* Gforth in pipes::
* Gforth in pipes:: Piping into or out of Gforth
* Startup speed:: When 14ms is not fast enough ...
Forth Tutorial
......@@ -374,6 +374,7 @@ Gforth locals
* How long do locals live?::
* Locals programming style::
* Locals implementation::
* Closures::
Structures
......@@ -429,6 +430,7 @@ Programming Tools
* Debugging:: Simple and quick.
* Assertions:: Making your programs self-checking.
* Singlestep Debugger:: Executing your program word by word.
* Code Coverage:: Measure execution frequency.
Multitasker
......@@ -662,10 +664,10 @@ material in this chapter.
* Invoking Gforth:: Getting in
* Leaving Gforth:: Getting out
* Help on Gforth:: Getting help
* Command-line editing::
* Command-line editing:: Gforth's command-line editor
* Environment variables:: that affect how Gforth starts up
* Gforth Files:: What gets installed and where
* Gforth in pipes::
* Gforth in pipes:: Piping into or out of Gforth
* Startup speed:: When 14ms is not fast enough ...
@end menu
......@@ -1134,8 +1136,8 @@ You can select different places for installation by using
@section Gforth in pipes
@cindex pipes, Gforth as part of
Gforth can be used in pipes created elsewhere (described here). It can
also create pipes on its own (@pxref{Pipes}).
Gforth can be used in pipes created elsewhere (described in the
following). It can also create pipes on its own (@pxref{Pipes}).
@cindex input from pipes
If you pipe into Gforth, your program should read with @code{read-file}
......@@ -4605,7 +4607,7 @@ program must use upper case for all Standard words. You can use whatever
case you like for words that you define, but in a Standard program you
have to use the words in the same case that you defined them.
Gforth supports case sensitivity through @code{table}s (case-sensitive
Gforth supports case sensitivity through @code{cs-wordlist}s (case-sensitive
wordlists, @pxref{Word Lists}).
Two people have asked how to convert Gforth to be case-sensitive; while
......@@ -10442,7 +10444,7 @@ they are no longer visible in any control-flow path. In a few cases
this may lead to increased space needs for the locals name area, but
usually less than reclaiming this space would cost in code size.
@node Closures, , Locals implementation, Gforth locals
@node Closures, , Locals implementation, Gforth locals
@subsubsection Closures
@cindex closures
......@@ -12401,7 +12403,7 @@ mixture of the @file{objects.fs} and @file{oof.fs} models.
* Debugging:: Simple and quick.
* Assertions:: Making your programs self-checking.
* Singlestep Debugger:: Executing your program word by word.
* Code Coverage:: Check how much code is used.
* Code Coverage:: Measure execution frequency.
@end menu
@node Examining, Forgetting words, Programming Tools, Programming Tools
......@@ -12679,36 +12681,48 @@ doc-break:
doc-break"
@c -------------------------------------------------------------
@node Code Coverage, , Singlestep Debugger, Programming Tools
@subsection Code Coverage
@node Code Coverage, , Singlestep Debugger, Programming Tools
@subsection Code Coverage and Execution Frequency
@cindex code coverage
@cindex execution frequency
If you run extensive tests on your code, you often want to figure out
if all parts of the code run, so measuring code coverage is
important. Gforth has a file @file{coverage.fs}, which contains the
necessary tools.
Code coverage inserts code into crucial positions of a word. Each
time that code is run, a specific counter is incremented, so you can
know how often that part is executed. You can save and reload the
coverage counters in binary format, and use that to annotate the
source files. Annotation is done by ANSI color escape sequences, so
the coverage shows nicely in the terminal.
doc-coverage?
doc-nocov[
doc-]nocov
doc-cov+
doc-.cover-raw
doc-.cover-file
doc-color-cover
doc-bw-cover
doc-covered?
if the tests exercise all parts of the code. This is called (test)
coverage. The file @file{coverage.fs} contains tools for measuring
the coverage as well as execution frequency.
Code coverage inserts counting code in every basic block
(straight-line code sequence) loaded after @file{coverage.fs}. Each
time that code is run, it increments the counter for that basic block.
Later you can show the source file with the counts inserted in these
basic blocks.
doc-.coverage
doc-annotate-cov
doc-cov%
doc-.cover-raw
@c commented out because the included-file index is not a
@c user-friendly way to pass a file (yet).
@c doc-.cover-file
@c doc-covered?
By default, the counts are shown in colour (using ANSI escape
sequences), but you can use @code{bw-cover} to show them in
parenthesized form without escape sequences.
doc-bw-cover
doc-color-cover
You can save and reload the coverage counters in binary format, to
aggregate coverage counters across several test runs.
doc-save-cov
doc-load-cov
doc-cov%
doc-cov+
@c commented out because these words have no effect (yet?)
@c doc-coverage?
@c doc-nocov[
@c doc-]nocov
@c -------------------------------------------------------------
@node Multitasker, C Interface, Programming Tools, Words
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment