ccanlint: add "_info ported" (for ccan/altstack).
[ccan] / doc / ccanlint.1.txt
1 CCANLINT(1)
2 ===========
3 :doctype: manpage
4
5
6 NAME
7 ----
8 ccanlint - Make CCAN code modules, and the brightness up.
9
10
11 SYNOPSIS
12 --------
13 *ccanlint* ['OPTIONS'] ['DIRECTORY'...]
14
15
16 DESCRIPTION
17 -----------
18 No encoder? No need to *ccanlint*. You programmer?  Excited to *ccanlint*!
19
20 CCAN module is small code of the song. *ccanlint* full CCAN testing
21 tool. Each test spray bit of wisdom. Also score. Good score good.
22 Bad score bad.
23
24 *ccanlint* expect the source code in this directory, or command line can be
25 more than one. Exit 0 happy if all modules all tests happy.
26
27 OPTIONS
28 -------
29 *-v, --verbose*::
30   Make *ccanlint* talkative. "-vv" doing very talkative. "-vvvv" make stupid talker.
31
32 *-n, --safe-mode*::
33   Do not compile anything. Could it be safer for the bad code, but *ccanlint*
34   sad useless.
35
36 *-l, --list-tests*::
37   Tests show *ccanlint* can do. Then die happy.
38
39 *--test-dep-graph*::
40   Chart of all parties *ccanlint* tests 'dot(1)' Graphviz, then die happy.
41
42 *-k, --keep*::
43   *ccanlint* normally make mess temporary directory, but now it later in
44   forensic.
45
46 *-s, --summary*::
47   *ccanlint* just realized there is no message unless you die horrible.
48
49 *-x, --exclude*='TESTNAME'::
50   No test run. Can the use of time many, many do *ccanlint* very, very quickly.
51   Often hatred 'tests_run_valgrind' that the test slowed.
52
53 *--timeout*='MILLISECONDS'::
54   Stop the test and forget it if you take too long. Generally, the same works as
55   '-x tests_run_valgrind'.
56
57 *-t, --target*='TESTNAME'::
58   Do not run all tests. Run this test, and the proof you need. Used many times
59   for many tests.
60
61 *--compiler*='COMPILER'::
62   *ccanlint* read config.h about finding 'CCAN_COMPILER'. Otherwise use the default
63   when it was built. The change, to use this compiler.
64
65 *--cflags*='CFLAGS'::
66   Set compiler options to compile. Be sure to protect spaces shell hunger.
67
68
69 TESTS
70 -----
71 *ccanlint* many tests. Each test will score soon. Not total score for
72 each test unless stupid module or no life.  Worry if little or low
73 score score after hacking.
74
75 If test break, but not repair, or maybe the dumb test, put the magic
76 lines '_info' file like this.  *ccanlint* to score from 0 of 1 for
77 test, but happy:
78 ---------------------------------------------------------------------
79  * Ccanlint:
80  *      // Test module foolish for me great!
81  *      info_documentation_exists FAIL
82  *      // Error for the file may be only
83  *      tests_pass_valgrind_noleaks test/run-mytest.c:FAIL
84 ---------------------------------------------------------------------
85
86 *info_exists*::
87   CCAN module must have '_info' file describing. No this score is 0.
88   However, *ccanlint* question may help to write one.
89
90 *depends_exist*::
91   '_info' file CCAN other module without saying, must find. It is not score 0.
92
93 *objects_build*::
94   All build purposes '.c' in the top dir. Not score 0.
95
96 *module_builds*::
97   Link to all objects in an object module. Not score 0.
98
99 *depends_accurate*::
100   Include other CCAN modules, we must say we need to '_info' depends.
101   Only one thing allows different, you can use 'ccan/tap' for testing anyway.
102
103 *depends_build*::
104   We try to generate the CCAN module you need.
105
106 *examples_exist*::
107   Rather hope that the comments in the header, and '_info'.  An
108   example of the section in each, please! Maybe more, *ccanlint* very
109   happy morning.
110
111 *examples_relevant*::
112   Example, do not cut and paste away! You say the name of the thing in
113   the example or *ccanlint* unhappy.
114
115 *hash_if*::
116   Module wants *ccanlint* 'config.h' "#define HAVE_FEATURE" for all
117   feature. Function test "#if HAVE_FEATURE" no "#ifdef HAVE_FEATURE"
118   because user might not know about the role at all.  Intelligent GCC
119   flag '-Wundef' say HAVE_FEATURE not 0, not 1! but only if the
120   use of '#if'.
121
122 *info_documentation_exists*::
123   '_info' file format is pretty comments. Copying someone. It is not difficult
124   write documentation!
125
126 *info_summary_single_line*::
127   Comments from a top line often describe the function or macro. '_info' comment
128   top line describes complete module. Characteristics make you scream!
129
130 *license_exists*::
131   The lawyers eat me. '_info' have 'License:' in the observation and LICENSE
132   file there.  In general, is the link: *ccanlint* offer create a link, if they
133   know 'License:'.
134
135 *license_comment*::
136   Attorney everywhere. Please put a comment saying something like "GPL
137   Version 4. Read LICENSE." in all source files in the directory.
138
139 *license_file_compat*::
140   Do not lie about the license! *ccanlint* search files, see the license
141   of another, angry here.
142
143 *license_depends_compat*::
144   Hostile to BSD license module, but requires another module of the GPL.
145   Perhaps poor encoder think all BSD code, unloading and damage
146   attorney stick! Ay ay!
147
148 *main_header_exists*::
149   *ccanlint* know the module name directory name. Expect the same name for
150   header.
151
152 *headers_idempotent*::
153   Good header '#include' many time happy.  Rap header around easy.
154   *ccanlint* say it can fix too.  Always work.
155
156 *main_header_compiles*::
157   Simple program '#include' main header compile.
158
159 *avoids_cpp_reserved*::
160   C\++ programmer to include code.  Not like them anyway, maybe, but wrong
161   end your program, do mourn.  Only main header compile C\++ and if
162   trying to compile C\++ module stupid to pieces.
163
164 *no_trailing_whitespace*::
165   Linux kernel programmers more, solve the problem for the space of
166   the final ban the line. Now all lots of hackers working to fix
167   it. Want to famous and Linux? Leave extra space too!
168
169 *examples_compile*::
170   *ccanlint* very smart! Take 'Example:' from a comment in the header and
171   '_info'. First try to compile anything.  If not, add many
172   headers and maybe put inside the function.  It does not work, adds
173   the latest example.  If the last example has '...' try that maybe. Sometimes
174   too complicated! '-vv' or '--keep' to see why it broke. Or maybe
175   bad example *ccanlint* says wow!
176
177 *examples_run*::
178   If the example program that comments like '// [Given "foo"] outputs
179   "bar"' then *ccanlint* will run the program with 'foo' in the
180   command line and standard input.  Happy if 'bar' are out and exit 0.
181   If quotes around 'bar' exact match needed; without quotes whitespace matches
182   any other space and trailing ignored.  \n is also supported for
183   matching.  You can also '"output contains"' to pass if the output
184   contains the string.
185
186 *module_links*::
187   CCAN link to the program module simply no error.
188
189 *objects_build_with_stringchecks*::
190   Module 'ccan/str' is super difficult to detect errors debugging chain.
191   *ccanlint* use with the module and see break!
192
193 *tests_exist*::
194   You have CCAN module directory called 'test'. You have proof
195   here. If there is no proof, *ccanlint* still offer make proof for
196   you.
197
198 *tests_compile*::
199   In 'test' which has four such tests, start with different
200   name. 'run' compile the test files, but no link to the module, you
201   '#include' to get the bits of the module. 'api' test compile and
202   link with the module. 'compile-ok' as 'run' but only build.
203   'compile-fail' compile, but when 'FAIL' set has to break or
204   alert. This good for module supposed to warn.
205
206 *test_helpers_compile*::
207   Other files 'test'? Compilation of links to all tests. Ask for help.
208
209 *tests_pass*::
210   'run' and 'api' test happy departure. If not happy, offer debugger.
211
212 *tests_pass_valgrind*::
213   *valgrind* the tool of all 'run' and 'api' slow test.  However, we
214   found many errors! If *valgrind* test rest, '_info' have *ccanlint* section,
215   make "tests_pass_valgrind test/TESTNAME:FAIL".  If required
216   valgrind additional option, "tests_pass_valgrind test/TESTNAME:--option".
217
218 *tests_pass_valgrind_noleaks*::
219   *valgrind* complain if the memory leak test. '_info' can also be disabled.
220
221 *tests_compile_coverage*::
222   Compile 'run', 'api' test coverage. Fun if not here!
223
224 *tests_coverage*::
225   Run tests again, find lines that never try! Half of the lines 1
226   point 3/4 getting 2 points. Limit of 5 points, but the extra point
227   for all lines of evidence.  Not win unless the module silly or use
228   gimmick 'ccan/failtest'.
229
230 *reduce_features*::
231   Code use 'HAVE_FEATURE' make special config.h turned off.  Not
232   stupid like HAVE_BIG_ENDIAN though!
233
234 *depends_build_without_features*::
235   Make modules CCAN need. config.h but not more features.
236
237 *objects_build_without_features*::
238   Make the module again, but not more features.
239
240 *tests_helpers_compile_without_features*::
241   Helpers do try again, but not more features.
242
243 *tests_compile_without_features*::
244   Collect the tests again, but not more features.
245
246 *tests_pass_without_features*:
247   Run tests again, but not more features.
248
249 BUGS
250 ----
251 *ccanlint* rapid change. The bad man, bad page.
252
253 AUTHOR
254 ------
255 Rusty Russell wrote *ccanlint*. Helping others, but most break Rusty.
256
257
258 RESOURCES
259 ---------
260 Main web site: http://ccodearchive.net/
261
262 Wiki: https://github.com/rustyrussell/ccan/wiki/
263
264 COPYING
265 -------
266 This program is free software; you can redistribute it and/or modify it
267 under the terms of the GNU General Public License as published by the Free
268 Software Foundation; either version 2 of the License, or (at your option)
269 any later version.