tools/configurator: fix compile error with -O2
[ccan] / doc / ccanlint.1
1 '\" t
2 .\"     Title: ccanlint
3 .\"    Author: [see the "AUTHOR" section]
4 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
5 .\"      Date: 09/28/2015
6 .\"    Manual: \ \&
7 .\"    Source: \ \&
8 .\"  Language: English
9 .\"
10 .TH "CCANLINT" "1" "09/28/2015" "\ \&" "\ \&"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el       .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 ccanlint \- Make CCAN code modules, and the brightness up\&.
32 .SH "SYNOPSIS"
33 .sp
34 \fBccanlint\fR [\fIOPTIONS\fR] [\fIDIRECTORY\fR\&...]
35 .SH "DESCRIPTION"
36 .sp
37 No encoder? No need to \fBccanlint\fR\&. You programmer? Excited to \fBccanlint\fR!
38 .sp
39 CCAN module is small code of the song\&. \fBccanlint\fR full CCAN testing tool\&. Each test spray bit of wisdom\&. Also score\&. Good score good\&. Bad score bad\&.
40 .sp
41 \fBccanlint\fR expect the source code in this directory, or command line can be more than one\&. Exit 0 happy if all modules all tests happy\&.
42 .SH "OPTIONS"
43 .PP
44 \fB\-v, \-\-verbose\fR
45 .RS 4
46 Make
47 \fBccanlint\fR
48 talkative\&. "\-vv" doing very talkative\&. "\-vvvv" make stupid talker\&.
49 .RE
50 .PP
51 \fB\-n, \-\-safe\-mode\fR
52 .RS 4
53 Do not compile anything\&. Could it be safer for the bad code, but
54 \fBccanlint\fR
55 sad useless\&.
56 .RE
57 .PP
58 \fB\-l, \-\-list\-tests\fR
59 .RS 4
60 Tests show
61 \fBccanlint\fR
62 can do\&. Then die happy\&.
63 .RE
64 .PP
65 \fB\-\-test\-dep\-graph\fR
66 .RS 4
67 Chart of all parties
68 \fBccanlint\fR
69 tests
70 \fIdot(1)\fR
71 Graphviz, then die happy\&.
72 .RE
73 .PP
74 \fB\-k, \-\-keep\fR
75 .RS 4
76 \fBccanlint\fR
77 normally make mess temporary directory, but now it later in forensic\&.
78 .RE
79 .PP
80 \fB\-s, \-\-summary\fR
81 .RS 4
82 \fBccanlint\fR
83 just realized there is no message unless you die horrible\&.
84 .RE
85 .PP
86 \fB\-x, \-\-exclude\fR=\fITESTNAME\fR
87 .RS 4
88 No test run\&. Can the use of time many, many do
89 \fBccanlint\fR
90 very, very quickly\&. Often hatred
91 \fItests_run_valgrind\fR
92 that the test slowed\&.
93 .RE
94 .PP
95 \fB\-\-timeout\fR=\fIMILLISECONDS\fR
96 .RS 4
97 Stop the test and forget it if you take too long\&. Generally, the same works as
98 \fI\-x tests_run_valgrind\fR\&.
99 .RE
100 .PP
101 \fB\-t, \-\-target\fR=\fITESTNAME\fR
102 .RS 4
103 Do not run all tests\&. Run this test, and the proof you need\&. Used many times for many tests\&.
104 .RE
105 .PP
106 \fB\-\-compiler\fR=\fICOMPILER\fR
107 .RS 4
108 \fBccanlint\fR
109 read config\&.h about finding
110 \fICCAN_COMPILER\fR\&. Otherwise use the default when it was built\&. The change, to use this compiler\&.
111 .RE
112 .PP
113 \fB\-\-cflags\fR=\fICFLAGS\fR
114 .RS 4
115 Set compiler options to compile\&. Be sure to protect spaces shell hunger\&.
116 .RE
117 .SH "TESTS"
118 .sp
119 \fBccanlint\fR many tests\&. Each test will score soon\&. Not total score for each test unless stupid module or no life\&. Worry if little or low score score after hacking\&.
120 .sp
121 If test break, but not repair, or maybe the dumb test, put the magic lines \fI_info\fR file like this\&. \fBccanlint\fR to score from 0 of 1 for test, but happy:
122 .sp
123 .if n \{\
124 .RS 4
125 .\}
126 .nf
127  * Ccanlint:
128  *      // Test module foolish for me great!
129  *      info_documentation_exists FAIL
130  *      // Error for the file may be only
131  *      tests_pass_valgrind_noleaks test/run\-mytest\&.c:FAIL
132 .fi
133 .if n \{\
134 .RE
135 .\}
136 .PP
137 \fBinfo_exists\fR
138 .RS 4
139 CCAN module must have
140 \fI_info\fR
141 file describing\&. No this score is 0\&. However,
142 \fBccanlint\fR
143 question may help to write one\&.
144 .RE
145 .PP
146 \fBdepends_exist\fR
147 .RS 4
148 \fI_info\fR
149 file CCAN other module without saying, must find\&. It is not score 0\&.
150 .RE
151 .PP
152 \fBobjects_build\fR
153 .RS 4
154 All build purposes
155 \fI\&.c\fR
156 in the top dir\&. Not score 0\&.
157 .RE
158 .PP
159 \fBmodule_builds\fR
160 .RS 4
161 Link to all objects in an object module\&. Not score 0\&.
162 .RE
163 .PP
164 \fBdepends_accurate\fR
165 .RS 4
166 Include other CCAN modules, we must say we need to
167 \fI_info\fR
168 depends\&. Only one thing allows different, you can use
169 \fIccan/tap\fR
170 for testing anyway\&.
171 .RE
172 .PP
173 \fBdepends_build\fR
174 .RS 4
175 We try to generate the CCAN module you need\&.
176 .RE
177 .PP
178 \fBexamples_exist\fR
179 .RS 4
180 Rather hope that the comments in the header, and
181 \fI_info\fR\&. An example of the section in each, please! Maybe more,
182 \fBccanlint\fR
183 very happy morning\&.
184 .RE
185 .PP
186 \fBexamples_relevant\fR
187 .RS 4
188 Example, do not cut and paste away! You say the name of the thing in the example or
189 \fBccanlint\fR
190 unhappy\&.
191 .RE
192 .PP
193 \fBhash_if\fR
194 .RS 4
195 Module wants
196 \fBccanlint\fR\fIconfig\&.h\fR
197 "#define HAVE_FEATURE" for all feature\&. Function test "#if HAVE_FEATURE" no "#ifdef HAVE_FEATURE" because user might not know about the role at all\&. Intelligent GCC flag
198 \fI\-Wundef\fR
199 say HAVE_FEATURE not 0, not 1! but only if the use of
200 \fI#if\fR\&.
201 .RE
202 .PP
203 \fBinfo_documentation_exists\fR
204 .RS 4
205 \fI_info\fR
206 file format is pretty comments\&. Copying someone\&. It is not difficult write documentation!
207 .RE
208 .PP
209 \fBinfo_summary_single_line\fR
210 .RS 4
211 Comments from a top line often describe the function or macro\&.
212 \fI_info\fR
213 comment top line describes complete module\&. Characteristics make you scream!
214 .RE
215 .PP
216 \fBlicense_exists\fR
217 .RS 4
218 The lawyers eat me\&.
219 \fI_info\fR
220 have
221 \fILicense:\fR
222 in the observation and LICENSE file there\&. In general, is the link:
223 \fBccanlint\fR
224 offer create a link, if they know
225 \fILicense:\fR\&.
226 .RE
227 .PP
228 \fBlicense_comment\fR
229 .RS 4
230 Attorney everywhere\&. Please put a comment saying something like "GPL Version 4\&. Read LICENSE\&." in all source files in the directory\&.
231 .RE
232 .PP
233 \fBlicense_file_compat\fR
234 .RS 4
235 Do not lie about the license!
236 \fBccanlint\fR
237 search files, see the license of another, angry here\&.
238 .RE
239 .PP
240 \fBlicense_depends_compat\fR
241 .RS 4
242 Hostile to BSD license module, but requires another module of the GPL\&. Perhaps poor encoder think all BSD code, unloading and damage attorney stick! Ay ay!
243 .RE
244 .PP
245 \fBmain_header_exists\fR
246 .RS 4
247 \fBccanlint\fR
248 know the module name directory name\&. Expect the same name for header\&.
249 .RE
250 .PP
251 \fBheaders_idempotent\fR
252 .RS 4
253 Good header
254 \fI#include\fR
255 many time happy\&. Rap header around easy\&.
256 \fBccanlint\fR
257 say it can fix too\&. Always work\&.
258 .RE
259 .PP
260 \fBmain_header_compiles\fR
261 .RS 4
262 Simple program
263 \fI#include\fR
264 main header compile\&.
265 .RE
266 .PP
267 \fBavoids_cpp_reserved\fR
268 .RS 4
269 C++ programmer to include code\&. Not like them anyway, maybe, but wrong end your program, do mourn\&. Only main header compile C++ and if trying to compile C\e++ module stupid to pieces\&.
270 .RE
271 .PP
272 \fBno_trailing_whitespace\fR
273 .RS 4
274 Linux kernel programmers more, solve the problem for the space of the final ban the line\&. Now all lots of hackers working to fix it\&. Want to famous and Linux? Leave extra space too!
275 .RE
276 .PP
277 \fBexamples_compile\fR
278 .RS 4
279 \fBccanlint\fR
280 very smart! Take
281 \fIExample:\fR
282 from a comment in the header and
283 \fI_info\fR\&. First try to compile anything\&. If not, add many headers and maybe put inside the function\&. It does not work, adds the latest example\&. If the last example has
284 \fI\&...\fR
285 try that maybe\&. Sometimes too complicated!
286 \fI\-vv\fR
287 or
288 \fI\-\-keep\fR
289 to see why it broke\&. Or maybe bad example
290 \fBccanlint\fR
291 says wow!
292 .RE
293 .PP
294 \fBexamples_run\fR
295 .RS 4
296 If the example program that comments like
297 \fI// Given "foo" outputs "bar"\fR\fBccanlint\fR
298 will run the program with
299 \fIfoo\fR
300 in the command line and standard input\&. Happy if
301 \fIbar\fR
302 are out\&. If quotes around
303 \fIbar\fR
304 exact match needed; without quotes whitespace matches any other space and trailing ignored\&. \en is also supported for matching\&. You can also
305 \fI"output contains"\fR
306 to pass if the output contains the string\&.
307 .RE
308 .PP
309 \fBmodule_links\fR
310 .RS 4
311 CCAN link to the program module simply no error\&.
312 .RE
313 .PP
314 \fBobjects_build_with_stringchecks\fR
315 .RS 4
316 Module
317 \fIccan/str\fR
318 is super difficult to detect errors debugging chain\&.
319 \fBccanlint\fR
320 use with the module and see break!
321 .RE
322 .PP
323 \fBtests_exist\fR
324 .RS 4
325 You have CCAN module directory called
326 \fItest\fR\&. You have proof here\&. If there is no proof,
327 \fBccanlint\fR
328 still offer make proof for you\&.
329 .RE
330 .PP
331 \fBtests_compile\fR
332 .RS 4
333 In
334 \fItest\fR
335 which has four such tests, start with different name\&.
336 \fIrun\fR
337 compile the test files, but no link to the module, you
338 \fI#include\fR
339 to get the bits of the module\&.
340 \fIapi\fR
341 test compile and link with the module\&.
342 \fIcompile\-ok\fR
343 as
344 \fIrun\fR
345 but only build\&.
346 \fIcompile\-fail\fR
347 compile, but when
348 \fIFAIL\fR
349 set has to break or alert\&. This good for module supposed to warn\&.
350 .RE
351 .PP
352 \fBtest_helpers_compile\fR
353 .RS 4
354 Other files
355 \fItest\fR? Compilation of links to all tests\&. Ask for help\&.
356 .RE
357 .PP
358 \fBtests_pass\fR
359 .RS 4
360 \fIrun\fR
361 and
362 \fIapi\fR
363 test happy departure\&. If not happy, offer debugger\&.
364 .RE
365 .PP
366 \fBtests_pass_valgrind\fR
367 .RS 4
368 \fBvalgrind\fR
369 the tool of all
370 \fIrun\fR
371 and
372 \fIapi\fR
373 slow test\&. However, we found many errors! If
374 \fBvalgrind\fR
375 test rest,
376 \fI_info\fR
377 have
378 \fBccanlint\fR
379 section, make "tests_pass_valgrind test/TESTNAME:FAIL"\&. If required valgrind additional option, "tests_pass_valgrind test/TESTNAME:\-\-option"\&.
380 .RE
381 .PP
382 \fBtests_pass_valgrind_noleaks\fR
383 .RS 4
384 \fBvalgrind\fR
385 complain if the memory leak test\&.
386 \fI_info\fR
387 can also be disabled\&.
388 .RE
389 .PP
390 \fBtests_compile_coverage\fR
391 .RS 4
392 Compile
393 \fIrun\fR,
394 \fIapi\fR
395 test coverage\&. Fun if not here!
396 .RE
397 .PP
398 \fBtests_coverage\fR
399 .RS 4
400 Run tests again, find lines that never try! Half of the lines 1 point 3/4 getting 2 points\&. Limit of 5 points, but the extra point for all lines of evidence\&. Not win unless the module silly or use gimmick
401 \fIccan/failtest\fR\&.
402 .RE
403 .PP
404 \fBreduce_features\fR
405 .RS 4
406 Code use
407 \fIHAVE_FEATURE\fR
408 make special config\&.h turned off\&. Not stupid like HAVE_BIG_ENDIAN though!
409 .RE
410 .PP
411 \fBdepends_build_without_features\fR
412 .RS 4
413 Make modules CCAN need\&. config\&.h but not more features\&.
414 .RE
415 .PP
416 \fBobjects_build_without_features\fR
417 .RS 4
418 Make the module again, but not more features\&.
419 .RE
420 .PP
421 \fBtests_helpers_compile_without_features\fR
422 .RS 4
423 Helpers do try again, but not more features\&.
424 .RE
425 .PP
426 \fBtests_compile_without_features\fR
427 .RS 4
428 Collect the tests again, but not more features\&.
429 .RE
430 .sp
431 \fBtests_pass_without_features\fR: Run tests again, but not more features\&.
432 .SH "BUGS"
433 .sp
434 \fBccanlint\fR rapid change\&. The bad man, bad page\&.
435 .SH "AUTHOR"
436 .sp
437 Rusty Russell wrote \fBccanlint\fR\&. Helping others, but most break Rusty\&.
438 .SH "RESOURCES"
439 .sp
440 Main web site: http://ccodearchive\&.net/
441 .sp
442 Wiki: https://github\&.com/rustyrussell/ccan/wiki/
443 .SH "COPYING"
444 .sp
445 This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version\&.