ccan/io: add examples.
[ccan] / doc / ccanlint.1
1 '\" t
2 .\"     Title: ccanlint
3 .\"    Author: [see the "AUTHOR" section]
4 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
5 .\"      Date: 12/05/2011
6 .\"    Manual: \ \&
7 .\"    Source: \ \&
8 .\"  Language: English
9 .\"
10 .TH "CCANLINT" "1" "12/05/2011" "\ \&" "\ \&"
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 bad score\&.
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
77 \fBccanlint\fR
78 normally make mess temporary directory, but now it later in forensic\&.
79 .RE
80 .PP
81 \fB\-s, \-\-summary\fR
82 .RS 4
83
84 \fBccanlint\fR
85 just realized there is no message unless you die horrible\&.
86 .RE
87 .PP
88 \fB\-x, \-\-exclude\fR=\fITESTNAME\fR
89 .RS 4
90 No test run\&. Can the use of time many, many do
91 \fBccanlint\fR
92 very, very quickly\&. Often hatred
93 \fItests_run_valgrind\fR
94 that the test slowed\&.
95 .RE
96 .PP
97 \fB\-\-timeout\fR=\fIMILLISECONDS\fR
98 .RS 4
99 Stop the test and forget it if you take too long\&. Generally, the same works as
100 \fI\-x tests_run_valgrind\fR\&.
101 .RE
102 .PP
103 \fB\-t, \-\-target\fR=\fITESTNAME\fR
104 .RS 4
105 Do not run all tests\&. Run this test, and the proof you need\&. Used many times for many tests\&.
106 .RE
107 .PP
108 \fB\-\-compiler\fR=\fICOMPILER\fR
109 .RS 4
110
111 \fBccanlint\fR
112 read config\&.h about finding
113 \fICCAN_COMPILER\fR\&. Otherwise use the default when it was built\&. The change, to use this compiler\&.
114 .RE
115 .PP
116 \fB\-\-cflags\fR=\fICFLAGS\fR
117 .RS 4
118 Set compiler options to compile\&. Be sure to protect spaces shell hunger\&.
119 .RE
120 .SH "TESTS"
121 .sp
122 \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\&.
123 .sp
124 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:
125 .sp
126 .if n \{\
127 .RS 4
128 .\}
129 .nf
130  * Ccanlint:
131  *      // Test module foolish for me great!
132  *      info_documentation_exists FAIL
133  *      // Error for the file may be only
134  *      tests_pass_valgrind_noleaks test/run\-mytest\&.c:FAIL
135 .fi
136 .if n \{\
137 .RE
138 .\}
139 .PP
140 \fBinfo_exists\fR
141 .RS 4
142 CCAN module must have
143 \fI_info\fR
144 file describing\&. No this score is 0\&. However,
145 \fBccanlint\fR
146 question may help to write one\&.
147 .RE
148 .PP
149 \fBdepends_exist\fR
150 .RS 4
151
152 \fI_info\fR
153 file CCAN other module without saying, must find\&. It is not score 0\&.
154 .RE
155 .PP
156 \fBobjects_build\fR
157 .RS 4
158 All build purposes
159 \fI\&.c\fR
160 in the top dir\&. Not score 0\&.
161 .RE
162 .PP
163 \fBmodule_builds\fR
164 .RS 4
165 Link to all objects in an object module\&. Not score 0\&.
166 .RE
167 .PP
168 \fBdepends_accurate\fR
169 .RS 4
170 Include other CCAN modules, we must say we need to
171 \fI_info\fR
172 depends\&. Only one thing allows different, you can use
173 \fIccan/tap\fR
174 for testing anyway\&.
175 .RE
176 .PP
177 \fBdepends_build\fR
178 .RS 4
179 We try to generate the CCAN module you need\&.
180 .RE
181 .PP
182 \fBexamples_exist\fR
183 .RS 4
184 Rather hope that the comments in the header, and
185 \fI_info\fR\&. An example of the section in each, please! Maybe more,
186 \fBccanlint\fR
187 very happy morning\&.
188 .RE
189 .PP
190 \fBexamples_relevant\fR
191 .RS 4
192 Example, do not cut and paste away! You say the name of the thing in the example or
193 \fBccanlint\fR
194 unhappy\&.
195 .RE
196 .PP
197 \fBhash_if\fR
198 .RS 4
199 Module wants
200 \fBccanlint\fR
201 \fIconfig\&.h\fR
202 "#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
203 \fI\-Wundef\fR
204 say HAVE_FEATURE not 0, not 1! but only if the use of
205 \fI#if\fR\&.
206 .RE
207 .PP
208 \fBinfo_documentation_exists\fR
209 .RS 4
210
211 \fI_info\fR
212 file format is pretty comments\&. Copying someone\&. It is not difficult write documentation!
213 .RE
214 .PP
215 \fBinfo_summary_single_line\fR
216 .RS 4
217 Comments from a top line often describe the function or macro\&.
218 \fI_info\fR
219 comment top line describes complete module\&. Characteristics make you scream!
220 .RE
221 .PP
222 \fBlicense_exists\fR
223 .RS 4
224 The lawyers eat me\&.
225 \fI_info\fR
226 have
227 \fILicense:\fR
228 in the observation and LICENSE file there\&. In general, is the link:
229 \fBccanlint\fR
230 offer create a link, if they know
231 \fILicense:\fR\&.
232 .RE
233 .PP
234 \fBlicense_comment\fR
235 .RS 4
236 Attorney everywhere\&. Please put a comment saying something like "GPL Version 4\&. Read LICENSE\&." in all source files in the directory\&.
237 .RE
238 .PP
239 \fBlicense_file_compat\fR
240 .RS 4
241 Do not lie about the license!
242 \fBccanlint\fR
243 search files, see the license of another, angry here\&.
244 .RE
245 .PP
246 \fBlicense_depends_compat\fR
247 .RS 4
248 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!
249 .RE
250 .PP
251 \fBmain_header_exists\fR
252 .RS 4
253
254 \fBccanlint\fR
255 know the module name directory name\&. Expect the same name for header\&.
256 .RE
257 .PP
258 \fBheaders_idempotent\fR
259 .RS 4
260 Good header
261 \fI#include\fR
262 many time happy\&. Rap header around easy\&.
263 \fBccanlint\fR
264 say it can fix too\&. Always work\&.
265 .RE
266 .PP
267 \fBmain_header_compiles\fR
268 .RS 4
269 Simple program
270 \fI#include\fR
271 main header compile\&.
272 .RE
273 .PP
274 \fBavoids_cpp_reserved\fR
275 .RS 4
276 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\&.
277 .RE
278 .PP
279 \fBno_trailing_whitespace\fR
280 .RS 4
281 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!
282 .RE
283 .PP
284 \fBexamples_compile\fR
285 .RS 4
286
287 \fBccanlint\fR
288 very smart! Take
289 \fIExample:\fR
290 from a comment in the header and
291 \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
292 \fI\&...\fR
293 try that maybe\&. Sometimes too complicated!
294 \fI\-vv\fR
295 or
296 \fI\-\-keep\fR
297 to see why it broke\&. Or maybe bad example
298 \fBccanlint\fR
299 says wow!
300 .RE
301 .PP
302 \fBexamples_run\fR
303 .RS 4
304 If the example program that comments like
305 \fI// given foo outputs bar\fR
306 \fBccanlint\fR
307 will run the food program
308 \fIfoo\fR
309 in the command line and standard input\&. Happy if
310 \fIbar\fR
311 are out\&. You can do \*(Aq or " about the production or determined\&. You can also
312 \fIoutput contains\fR
313 more relaxed controls\&.
314 .RE
315 .PP
316 \fBmodule_links\fR
317 .RS 4
318 CCAN link to the program module simply no error\&.
319 .RE
320 .PP
321 \fBobjects_build_with_stringchecks\fR
322 .RS 4
323 Module
324 \fIccan/str\fR
325 is super difficult to detect errors debugging chain\&.
326 \fBccanlint\fR
327 use with the module and see break!
328 .RE
329 .PP
330 \fBtests_exist\fR
331 .RS 4
332 You have CCAN module directory called
333 \fItest\fR\&. You have proof here\&. If there is no proof,
334 \fBccanlint\fR
335 still offer make proof for you\&.
336 .RE
337 .PP
338 \fBtests_compile\fR
339 .RS 4
340 In
341 \fItest\fR
342 which has four such tests, start with different name\&.
343 \fIrun\fR
344 compile the test files, but no link to the module, you
345 \fI#include\fR
346 to get the bits of the module\&.
347 \fIapi\fR
348 test compile and link with the module\&.
349 \fIcompile\-ok\fR
350 as
351 \fIrun\fR
352 but only build\&.
353 \fIcompile\-fail\fR
354 compile, but when
355 \fIFAIL\fR
356 set has to break or alert\&. This good for module supposed to warn\&.
357 .RE
358 .PP
359 \fBtest_helpers_compile\fR
360 .RS 4
361 Other files
362 \fItest\fR? Compilation of links to all tests\&. Ask for help\&.
363 .RE
364 .PP
365 \fBtests_pass\fR
366 .RS 4
367
368 \fIrun\fR
369 and
370 \fIapi\fR
371 test happy departure\&. If not happy, offer debugger\&.
372 .RE
373 .PP
374 \fBtests_pass_valgrind\fR
375 .RS 4
376
377 \fBvalgrind\fR
378 the tool of all
379 \fIrun\fR
380 and
381 \fIapi\fR
382 slow test\&. However, we found many errors! If
383 \fBvalgrind\fR
384 test rest,
385 \fI_info\fR
386 have
387 \fBccanlint\fR
388 section, make "tests_pass_valgrind test/TESTNAME:FAIL"\&. If required valgrind additional option, "tests_pass_valgrind test/TESTNAME:\-\-option"\&.
389 .RE
390 .PP
391 \fBtests_pass_valgrind_noleaks\fR
392 .RS 4
393
394 \fBvalgrind\fR
395 complain if the memory leak test\&.
396 \fI_info\fR
397 can also be disabled\&.
398 .RE
399 .PP
400 \fBtests_compile_coverage\fR
401 .RS 4
402 Compile
403 \fIrun\fR,
404 \fIapi\fR
405 test coverage\&. Fun if not here!
406 .RE
407 .PP
408 \fBtests_coverage\fR
409 .RS 4
410 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
411 \fIccan/failtest\fR\&.
412 .RE
413 .PP
414 \fBreduce_features\fR
415 .RS 4
416 Code use
417 \fIHAVE_FEATURE\fR
418 make special config\&.h turned off\&. Not stupid like HAVE_BIG_ENDIAN though!
419 .RE
420 .PP
421 \fBdepends_build_without_features\fR
422 .RS 4
423 Make modules CCAN need\&. config\&.h but not more features\&.
424 .RE
425 .PP
426 \fBobjects_build_without_features\fR
427 .RS 4
428 Make the module again, but not more features\&.
429 .RE
430 .PP
431 \fBtests_helpers_compile_without_features\fR
432 .RS 4
433 Helpers do try again, but not more features\&.
434 .RE
435 .PP
436 \fBtests_compile_without_features\fR
437 .RS 4
438 Collect the tests again, but not more features\&.
439 .RE
440 .sp
441 \fBtests_pass_without_features\fR: Run tests again, but not more features\&.
442 .SH "BUGS"
443 .sp
444 \fBccanlint\fR rapid change\&. The bad man, bad page\&.
445 .SH "AUTHOR"
446 .sp
447 Rusty Russell wrote \fBccanlint\fR\&. Helping others, but most break Rusty\&.
448 .SH "RESOURCES"
449 .sp
450 Main web site: http://ccodearchive\&.net/
451 .sp
452 Wiki: https://github\&.com/rustyrussell/ccan/wiki/
453 .SH "COPYING"
454 .sp
455 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\&.