xaizek / uncov (License: AGPLv3+) (since 2018-12-07)
Uncov(er) is a tool that collects and processes code coverage reports.
Clone URLs: https://code.reversed.top/user/xaizek/uncov ssh://rocketgit@code.reversed.top/user/xaizek/uncov
v0.1 v0.2 v0.3 v0.4 v0.5 master
Commit a11b4035df1e4535af389e59ac978e5da08d74e9

Add manual pages for uncov-gcov and uncov-web
Author: xaizek
Author date (UTC): 2017-09-18 14:54
Committer name: xaizek
Committer date (UTC): 2017-09-18 14:54
Parent(s): 38eb44ac85814b492616f3f31803e8fa7b4ff7e6
Signing key: 99DC5E4DB05F6BE2
Tree: 1ac373bc8f3df3ddc066eff7a75ef7c62f471111
File Lines added Lines deleted
INSTALL.md 1 1
Makefile 24 3
TODO.md 0 6
docs/uncov-gcov.1 112 0
docs/uncov-gcov/01-name.md 5 0
docs/uncov-gcov/02-synopsis.md 8 0
docs/uncov-gcov/03-options.md 101 0
docs/uncov-gcov/04-usage.md 26 0
docs/uncov-gcov/05-see-also.md 4 0
docs/uncov-web.1 63 0
docs/uncov-web/01-name.md 5 0
docs/uncov-web/02-synopsis.md 8 0
docs/uncov-web/03-options.md 32 0
docs/uncov-web/04-description.md 16 0
docs/uncov-web/05-files.md 0 0
docs/uncov-web/06-see-also.md 4 0
docs/uncov.1 3 0
docs/uncov/08-see-also.md 4 0
File INSTALL.md changed (mode: 100644) (index 54a02de..fe846eb)
... ... Builds debug version with undefined and address sanitizers enabled in
34 34
35 35 **`man`** **`man`**
36 36
37 Rebuilds manual page in `<out>/docs/uncov.1`, requires `pandoc`.
37 Rebuilds manual pages in `<out>/docs/`, requires `pandoc`.
38 38
39 39 **`doxygen`** **`doxygen`**
40 40
File Makefile changed (mode: 100644) (index 7bae909..97f9a8b)
... ... self-coverage: UNCOV_PREFIX := $(out_dir)/
121 121 self-coverage: GCOV_PREFIX := ./ self-coverage: GCOV_PREFIX := ./
122 122 self-coverage: coverage self-coverage: coverage
123 123
124 man: docs/uncov.1
125 # the next target doesn't depend on $(wildcard docs/*.md) to make pandoc
124 man: docs/uncov.1 docs/uncov-gcov.1 docs/uncov-web.1
125 # the following targets don't depend on $(wildcard docs/*/*.md) to make pandoc
126 126 # optional # optional
127 127 docs/uncov.1: force | $(out_dir)/docs/uncov docs/uncov.1: force | $(out_dir)/docs/uncov
128 128 pandoc -V title=uncov \ pandoc -V title=uncov \
 
... ... docs/uncov.1: force | $(out_dir)/docs/uncov
132 132 -V date="$$(date +'%B %d, %Y')" \ -V date="$$(date +'%B %d, %Y')" \
133 133 -V author='xaizek <xaizek@posteo.net>' \ -V author='xaizek <xaizek@posteo.net>' \
134 134 -s -o $@ $(sort $(wildcard docs/uncov/*.md)) -s -o $@ $(sort $(wildcard docs/uncov/*.md))
135 docs/uncov-gcov.1: force | $(out_dir)/docs/uncov-gcov
136 pandoc -V title=uncov-gcov \
137 -V section=1 \
138 -V app=uncov-gcov \
139 -V footer="uncov v0.1" \
140 -V date="$$(date +'%B %d, %Y')" \
141 -V author='xaizek <xaizek@posteo.net>' \
142 -s -o $@ $(sort $(wildcard docs/uncov-gcov/*.md))
143 docs/uncov-web.1: force | $(out_dir)/docs/uncov-web
144 pandoc -V title=uncov-web \
145 -V section=1 \
146 -V app=uncov-web \
147 -V footer="uncov v0.1" \
148 -V date="$$(date +'%B %d, %Y')" \
149 -V author='xaizek <xaizek@posteo.net>' \
150 -s -o $@ $(sort $(wildcard docs/uncov-web/*.md))
135 151
136 152 doxygen: doxygen:
137 153 doxygen doxygen/config doxygen doxygen/config
 
... ... install: release
166 182 $(INSTALL) -t $(DESTDIR)/usr/bin/ $(bin) $(webbin) uncov-gcov $(INSTALL) -t $(DESTDIR)/usr/bin/ $(bin) $(webbin) uncov-gcov
167 183 $(INSTALL) -t $(DESTDIR)/usr/share/uncov/srchilight/ data/srchilight/* $(INSTALL) -t $(DESTDIR)/usr/share/uncov/srchilight/ data/srchilight/*
168 184 $(INSTALL) -m 644 docs/uncov.1 $(DESTDIR)/usr/share/man/man1/uncov.1 $(INSTALL) -m 644 docs/uncov.1 $(DESTDIR)/usr/share/man/man1/uncov.1
185 $(INSTALL) -m 644 docs/uncov-gcov.1 \
186 $(DESTDIR)/usr/share/man/man1/uncov-gcov.1
187 $(INSTALL) -m 644 docs/uncov-web.1 $(DESTDIR)/usr/share/man/man1/uncov-web.1
169 188
170 189 uninstall: uninstall:
171 190 $(RM) $(DESTDIR)/usr/bin/$(basename $(bin)) \ $(RM) $(DESTDIR)/usr/bin/$(basename $(bin)) \
172 191 $(DESTDIR)/usr/bin/$(basename $(webbin)) \ $(DESTDIR)/usr/bin/$(basename $(webbin)) \
173 $(DESTDIR)/usr/bin/uncov-gcov $(DESTDIR)/usr/share/man/man1/uncov.1
192 $(DESTDIR)/usr/bin/uncov-gcov $(DESTDIR)/usr/share/man/man1/uncov.1 \
193 $(DESTDIR)/usr/share/man/man1/uncov-gcov.1 \
194 $(DESTDIR)/usr/share/man/man1/uncov-web.1
174 195 $(RM) -r $(DESTDIR)/usr/share/uncov/ $(RM) -r $(DESTDIR)/usr/share/uncov/
175 196
176 197 # work around parenthesis warning in tests somehow caused by ccache # work around parenthesis warning in tests somehow caused by ccache
File TODO.md changed (mode: 100644) (index 8319349..571bdb5)
... ... maybe even when branch ref matches build commit.
74 74
75 75 Maybe should also indicate "temporary" commits somehow. Maybe should also indicate "temporary" commits somehow.
76 76
77 ## Write manual pages for uncov-gcov and uncov-web. ##
78
79 | ID | Status | Type |
80 |------|-----------|--------|
81 | LSY | planned | task |
82
83 77 ## Source-highlight hangs if passed in std::istream is at EOF? ## ## Source-highlight hangs if passed in std::istream is at EOF? ##
84 78
85 79 | ID | Status | Type | | ID | Status | Type |
File docs/uncov-gcov.1 added (mode: 100644) (index 0000000..d185449)
1 .\" Automatically generated by Pandoc 1.17.0.3
2 .\"
3 .TH "uncov-gcov" "1" "September 18, 2017" "uncov v0.1" ""
4 .hy
5 .SH NAME
6 .PP
7 uncov\-gcov is coverage information collector for C and C++ languages to
8 be used with \f[B]uncov(1)\f[].
9 .SH SYNOPSIS
10 .PP
11 \f[B]uncov\-gcov\f[] \f[B]\-h|\-\-help\f[]
12 .PP
13 \f[B]uncov\-gcov\f[] \f[B]\-v|\-\-version\f[]
14 .PP
15 \f[B]uncov\-gcov\f[] \f[B][<options>...]\f[]
16 .SH OPTIONS
17 .SS \f[B]\-\-help, \-h\f[]
18 .PP
19 Displays short usage help.
20 .SS \f[B]\-\-version, \-v\f[]
21 .PP
22 Displays version information.
23 .SS \f[B]\-\-verbose\f[]
24 .PP
25 Print verbose messages.
26 .SS \f[B]\-\-dryrun\f[]
27 .PP
28 Run the script without printing report.
29 .SS \f[B]\-\-gcov\f[] [=gcov]
30 .PP
31 Set the location of gcov.
32 .SS \f[B]\-\-gcov\-options\f[] [=""]
33 .PP
34 Set the options given to gcov.
35 .SS \f[B]\-r\f[], \f[B]\-\-root\f[] [=.]
36 .PP
37 Set the root directory.
38 .SS \f[B]\-b\f[], \f[B]\-\-build\-root\f[] [={discovered}]
39 .PP
40 Set the directory from which gcov will be called; by default gcov is run
41 in the directory of the .o files; however the paths of the sources are
42 often relative to the directory from which the compiler was run and
43 these relative paths are saved in the .o file; when this happens, gcov
44 needs to run in the same directory as the compiler in order to find the
45 source files.
46 .SS \f[B]\-\-collect\-root\f[] [={value of \-\-root}]
47 .PP
48 Directory to look gcov files in.
49 .SS \f[B]\-e\f[], \f[B]\-\-exclude\f[] [=""]
50 .PP
51 Set exclude file or directory.
52 .SS \f[B]\-i\f[], \f[B]\-\-include\f[] [=""]
53 .PP
54 Set include file or directory.
55 .SS \f[B]\-E\f[], \f[B]\-\-exclude\-pattern\f[] [=""]
56 .PP
57 Set exclude file/directory pattern.
58 .SS \f[B]\-x\f[], \f[B]\-\-extension\f[]
59 [=.h,.hh,.hpp,.hxx,.c,.cc,.cpp,.cxx,.m,.mm]
60 .PP
61 Set extension of files to process.
62 .SS \f[B]\-n\f[], \f[B]\-\-no\-gcov\f[]
63 .PP
64 Do not run gcov.
65 .SS \f[B]\-\-encodings\f[] [=utf\-8,latin\-1]
66 .PP
67 Source encodings to try in order of preference.
68 .SS \f[B]\-\-dump\f[] <file>
69 .PP
70 Dump JSON payload to a file.
71 .SS \f[B]\-\-follow\-symlinks\f[]
72 .PP
73 Follow symlinks.
74 .SS \f[B]\-c\f[], \f[B]\-\-capture\-worktree\f[]
75 .PP
76 Make a dangling commit if working directory is dirty.
77 .SS \f[B]\-\-ref\-name\f[] [={discovered}]
78 .PP
79 Force custom ref name.
80 .SH USAGE
81 .PP
82 uncov\-gcov can be used to generate coverage, but it seems to not play
83 well with out\-of\-tree builds (some coverage is missing, this issue is
84 inherited from its origin), so the recommended way of recording coverage
85 information is as follows:
86 .IP
87 .nf
88 \f[C]
89 #\ reset\ coverage\ counters\ from\ previous\ runs
90 find\ .\ \-name\ \[aq]*.gcda\[aq]\ \-delete
91
92 #\ run\ tests\ here\ with\ something\ like\ `make\ check`
93
94 #\ generage\ coverage\ for\ every\ object\ file\ found\ (change\ "."\ to\ build\ root)
95 find\ .\ \-name\ \[aq]*.o\[aq]\ \-exec\ gcov\ \-p\ {}\ +
96
97 #\ generage\ and\ combine\ coverage\ reports\ (\-\-capture\-worktree\ automatically
98 #\ makes\ stray\ commit\ if\ repository\ is\ dirty)
99 uncov\-gcov\ \-\-root\ .\ \-\-no\-gcov\ \-\-capture\-worktree\ \-\-exclude\ tests\ |\ uncov\ new
100
101 #\ remove\ coverage\ reports
102 find\ .\ \-name\ \[aq]*.gcov\[aq]\ \-delete
103 \f[]
104 .fi
105 .PP
106 These commands can be put in a separate script or embedded directly into
107 build system.
108 .SH SEE ALSO
109 .PP
110 \f[B]uncov\f[](1), \f[B]uncov\-web\f[](1)
111 .SH AUTHORS
112 xaizek <xaizek@posteo.net>.
File docs/uncov-gcov/01-name.md added (mode: 100644) (index 0000000..262c88c)
1 NAME
2 ====
3
4 uncov-gcov is coverage information collector for C and C++ languages to be used
5 with **uncov(1)**.
File docs/uncov-gcov/02-synopsis.md added (mode: 100644) (index 0000000..55f999e)
1 SYNOPSIS
2 ========
3
4 **uncov-gcov** **-h|--help**
5
6 **uncov-gcov** **-v|--version**
7
8 **uncov-gcov** **[\<options\>...]**
File docs/uncov-gcov/03-options.md added (mode: 100644) (index 0000000..218b410)
1 OPTIONS
2 =======
3
4 **--help, -h**
5 --------------
6
7 Displays short usage help.
8
9 **--version, -v**
10 -----------------
11
12 Displays version information.
13
14 **--verbose**
15 -------------
16
17 Print verbose messages.
18
19 **--dryrun**
20 ------------
21
22 Run the script without printing report.
23
24 **--gcov** [=gcov]
25 ------------------
26
27 Set the location of gcov.
28
29 **--gcov-options** [=""]
30 ------------------------
31
32 Set the options given to gcov.
33
34 **-r**, **--root** [=.]
35 -----------------------
36
37 Set the root directory.
38
39 **-b**, **--build-root** [={discovered}]
40 ----------------------------------------
41
42 Set the directory from which gcov will be called; by default gcov is run in the
43 directory of the .o files; however the paths of the sources are often relative
44 to the directory from which the compiler was run and these relative paths are
45 saved in the .o file; when this happens, gcov needs to run in the same directory
46 as the compiler in order to find the source files.
47
48 **--collect-root** [={value of --root}]
49 ---------------------------------------
50
51 Directory to look gcov files in.
52
53 **-e**, **--exclude** [=""]
54 ---------------------------
55
56 Set exclude file or directory.
57
58 **-i**, **--include** [=""]
59 ---------------------------
60
61 Set include file or directory.
62
63 **-E**, **--exclude-pattern** [=""]
64 -----------------------------------
65
66 Set exclude file/directory pattern.
67
68 **-x**, **--extension** [=.h,.hh,.hpp,.hxx,.c,.cc,.cpp,.cxx,.m,.mm]
69 -------------------------------------------------------------------
70
71 Set extension of files to process.
72
73 **-n**, **--no-gcov**
74 ---------------------
75
76 Do not run gcov.
77
78 **--encodings** [=utf-8,latin-1]
79 --------------------------------
80
81 Source encodings to try in order of preference.
82
83 **--dump** \<file\>
84 -------------------
85
86 Dump JSON payload to a file.
87
88 **--follow-symlinks**
89 ---------------------
90
91 Follow symlinks.
92
93 **-c**, **--capture-worktree**
94 ------------------------------
95
96 Make a dangling commit if working directory is dirty.
97
98 **--ref-name** [={discovered}]
99 ------------------------------
100
101 Force custom ref name.
File docs/uncov-gcov/04-usage.md added (mode: 100644) (index 0000000..0689efb)
1 USAGE
2 =====
3
4 uncov-gcov can be used to generate coverage, but it seems to not play well with
5 out-of-tree builds (some coverage is missing, this issue is inherited from its
6 origin), so the recommended way of recording coverage information is as follows:
7
8 ```
9 # reset coverage counters from previous runs
10 find . -name '*.gcda' -delete
11
12 # run tests here with something like `make check`
13
14 # generage coverage for every object file found (change "." to build root)
15 find . -name '*.o' -exec gcov -p {} +
16
17 # generage and combine coverage reports (--capture-worktree automatically
18 # makes stray commit if repository is dirty)
19 uncov-gcov --root . --no-gcov --capture-worktree --exclude tests | uncov new
20
21 # remove coverage reports
22 find . -name '*.gcov' -delete
23 ```
24
25 These commands can be put in a separate script or embedded directly into build
26 system.
File docs/uncov-gcov/05-see-also.md added (mode: 100644) (index 0000000..9f57646)
1 SEE ALSO
2 ========
3
4 **uncov**(1), **uncov-web**(1)
File docs/uncov-web.1 added (mode: 100644) (index 0000000..cc60688)
1 .\" Automatically generated by Pandoc 1.17.0.3
2 .\"
3 .TH "uncov-web" "1" "September 18, 2017" "uncov v0.1" ""
4 .hy
5 .SH NAME
6 .PP
7 uncov\-web is a HTTP\-server that provides Web\-UI for browsing coverage
8 information collected by \f[B]uncov(1)\f[].
9 .SH SYNOPSIS
10 .PP
11 \f[B]uncov\-web\f[] \f[B]\-h|\-\-help\f[]
12 .PP
13 \f[B]uncov\-web\f[] \f[B]\-v|\-\-version\f[]
14 .PP
15 \f[B]uncov\-web\f[] \f[B]\-\-vhost\f[] <host\-name> \f[B]\-\-ip\f[]
16 [=0.0.0.0] \f[B]\-\-repo\f[] [=.] \f[B]\-\-port\f[] [=8000]
17 .SH OPTIONS
18 .SS \f[B]\-\-help, \-h\f[]
19 .PP
20 Displays short usage help.
21 .SS \f[B]\-\-version, \-v\f[]
22 .PP
23 Displays version information.
24 .SS \f[B]\-\-vhost\f[] <host\-name>
25 .PP
26 Sets virtual host name.
27 This option is mandatory.
28 .SS \f[B]\-\-ip\f[] [=0.0.0.0]
29 .PP
30 IP address to bind to.
31 The default is to bind to all interfaces.
32 .SS \f[B]\-\-repo\f[] [=.]
33 .PP
34 Path to repository.
35 .SS \f[B]\-\-port\f[] [=8000]
36 .PP
37 Post to listen on.
38 .SH DESCRIPTION
39 .PP
40 Once started provides HTTP\-server to view coverage reports.
41 Does not daemonize itself.
42 .SS Notations
43 .PP
44 For the sake of brevity interface uses several intuitive abbreviations:
45 .IP \[bu] 2
46 Cov \- coverage;
47 .IP \[bu] 2
48 Ref \- reference (of VCS);
49 .IP \[bu] 2
50 C \- covered;
51 .IP \[bu] 2
52 M \- missed;
53 .IP \[bu] 2
54 R \- relevant.
55 .SH FILES
56 .PP
57 \f[B]<repository\-directory>/uncov.sqlite\f[] \-\- storage of coverage
58 data.
59 .SH SEE ALSO
60 .PP
61 \f[B]uncov(1)\f[], \f[B]uncov\-gcov\f[](1)
62 .SH AUTHORS
63 xaizek <xaizek@posteo.net>.
File docs/uncov-web/01-name.md added (mode: 100644) (index 0000000..84785ea)
1 NAME
2 ====
3
4 uncov-web is a HTTP-server that provides Web-UI for browsing coverage
5 information collected by **uncov(1)**.
File docs/uncov-web/02-synopsis.md added (mode: 100644) (index 0000000..92316d4)
1 SYNOPSIS
2 ========
3
4 **uncov-web** **-h|--help**
5
6 **uncov-web** **-v|--version**
7
8 **uncov-web** **--vhost** \<host-name\> **--ip** [=0.0.0.0] **--repo** [=.] **--port** [=8000]
File docs/uncov-web/03-options.md added (mode: 100644) (index 0000000..df81e86)
1 OPTIONS
2 =======
3
4 **--help, -h**
5 --------------
6
7 Displays short usage help.
8
9 **--version, -v**
10 -----------------
11
12 Displays version information.
13
14 **--vhost** \<host-name\>
15 -------------------------
16
17 Sets virtual host name. This option is mandatory.
18
19 **--ip** [=0.0.0.0]
20 -------------------
21
22 IP address to bind to. The default is to bind to all interfaces.
23
24 **--repo** [=.]
25 ---------------
26
27 Path to repository.
28
29 **--port** [=8000]
30 ------------------
31
32 Post to listen on.
File docs/uncov-web/04-description.md added (mode: 100644) (index 0000000..c4c9576)
1 DESCRIPTION
2 ===========
3
4 Once started provides HTTP-server to view coverage reports. Does not daemonize
5 itself.
6
7 Notations
8 ---------
9
10 For the sake of brevity interface uses several intuitive abbreviations:
11
12 * Cov - coverage;
13 * Ref - reference (of VCS);
14 * C - covered;
15 * M - missed;
16 * R - relevant.
File docs/uncov-web/05-files.md copied from file docs/uncov/07-files.md (similarity 100%)
File docs/uncov-web/06-see-also.md added (mode: 100644) (index 0000000..000adf7)
1 SEE ALSO
2 ========
3
4 **uncov(1)**, **uncov-gcov**(1)
File docs/uncov.1 changed (mode: 100644) (index 8580cbf..69d8a24)
... ... Prints files of \f[B]<build>\f[] (or last build) located under
420 420 .PP .PP
421 421 \f[B]<repository\-directory>/uncov.sqlite\f[] \-\- storage of coverage \f[B]<repository\-directory>/uncov.sqlite\f[] \-\- storage of coverage
422 422 data. data.
423 .SH SEE ALSO
424 .PP
425 \f[B]uncov\-gcov\f[](1), \f[B]uncov\-web\f[](1)
423 426 .SH AUTHORS .SH AUTHORS
424 427 xaizek <xaizek@posteo.net>. xaizek <xaizek@posteo.net>.
File docs/uncov/08-see-also.md added (mode: 100644) (index 0000000..1bca46d)
1 SEE ALSO
2 ========
3
4 **uncov-gcov**(1), **uncov-web**(1)
Hints
Before first commit, do not forget to setup your git environment:
git config --global user.name "your_name_here"
git config --global user.email "your@email_here"

Clone this repository using HTTP(S):
git clone https://code.reversed.top/user/xaizek/uncov

Clone this repository using ssh (do not forget to upload a key first):
git clone ssh://rocketgit@code.reversed.top/user/xaizek/uncov

You are allowed to anonymously push to this repository.
This means that your pushed commits will automatically be transformed into a pull request:
... clone the repository ...
... make some changes and some commits ...
git push origin master