git.ozlabs.org Git - ccan/blob - 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\&.