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.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\&.