git.ozlabs.org Git - ccan/blob - 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 *info_ported*::
  91   CCAN module '_info' can say 'ported' arg; if says '0' not ported, few tests
  92   run.
  93
  94 *depends_exist*::
  95   '_info' file CCAN other module without saying, must find. It is not score 0.
  96
  97 *objects_build*::
  98   All build purposes '.c' in the top dir. Not score 0.
  99
 100 *module_builds*::
 101   Link to all objects in an object module. Not score 0.
 102
 103 *depends_accurate*::
 104   Include other CCAN modules, we must say we need to '_info' depends.
 105   Only one thing allows different, you can use 'ccan/tap' for testing anyway.
 106
 107 *depends_build*::
 108   We try to generate the CCAN module you need.
 109
 110 *examples_exist*::
 111   Rather hope that the comments in the header, and '_info'.  An
 112   example of the section in each, please! Maybe more, *ccanlint* very
 113   happy morning.
 114
 115 *examples_relevant*::
 116   Example, do not cut and paste away! You say the name of the thing in
 117   the example or *ccanlint* unhappy.
 118
 119 *hash_if*::
 120   Module wants *ccanlint* 'config.h' "#define HAVE_FEATURE" for all
 121   feature. Function test "#if HAVE_FEATURE" no "#ifdef HAVE_FEATURE"
 122   because user might not know about the role at all.  Intelligent GCC
 123   flag '-Wundef' say HAVE_FEATURE not 0, not 1! but only if the
 124   use of '#if'.
 125
 126 *info_documentation_exists*::
 127   '_info' file format is pretty comments. Copying someone. It is not difficult
 128   write documentation!
 129
 130 *info_summary_single_line*::
 131   Comments from a top line often describe the function or macro. '_info' comment
 132   top line describes complete module. Characteristics make you scream!
 133
 134 *license_exists*::
 135   The lawyers eat me. '_info' have 'License:' in the observation and LICENSE
 136   file there.  In general, is the link: *ccanlint* offer create a link, if they
 137   know 'License:'.
 138
 139 *license_comment*::
 140   Attorney everywhere. Please put a comment saying something like "GPL
 141   Version 4. Read LICENSE." in all source files in the directory.
 142
 143 *license_file_compat*::
 144   Do not lie about the license! *ccanlint* search files, see the license
 145   of another, angry here.
 146
 147 *license_depends_compat*::
 148   Hostile to BSD license module, but requires another module of the GPL.
 149   Perhaps poor encoder think all BSD code, unloading and damage
 150   attorney stick! Ay ay!
 151
 152 *main_header_exists*::
 153   *ccanlint* know the module name directory name. Expect the same name for
 154   header.
 155
 156 *headers_idempotent*::
 157   Good header '#include' many time happy.  Rap header around easy.
 158   *ccanlint* say it can fix too.  Always work.
 159
 160 *main_header_compiles*::
 161   Simple program '#include' main header compile.
 162
 163 *avoids_cpp_reserved*::
 164   C\++ programmer to include code.  Not like them anyway, maybe, but wrong
 165   end your program, do mourn.  Only main header compile C\++ and if
 166   trying to compile C\++ module stupid to pieces.
 167
 168 *no_trailing_whitespace*::
 169   Linux kernel programmers more, solve the problem for the space of
 170   the final ban the line. Now all lots of hackers working to fix
 171   it. Want to famous and Linux? Leave extra space too!
 172
 173 *examples_compile*::
 174   *ccanlint* very smart! Take 'Example:' from a comment in the header and
 175   '_info'. First try to compile anything.  If not, add many
 176   headers and maybe put inside the function.  It does not work, adds
 177   the latest example.  If the last example has '...' try that maybe. Sometimes
 178   too complicated! '-vv' or '--keep' to see why it broke. Or maybe
 179   bad example *ccanlint* says wow!
 180
 181 *examples_run*::
 182   If the example program that comments like '// [Given "foo"] outputs
 183   "bar"' then *ccanlint* will run the program with 'foo' in the
 184   command line and standard input.  Happy if 'bar' are out and exit 0.
 185   If quotes around 'bar' exact match needed; without quotes whitespace matches
 186   any other space and trailing ignored.  \n is also supported for
 187   matching.  You can also '"output contains"' to pass if the output
 188   contains the string.
 189
 190 *module_links*::
 191   CCAN link to the program module simply no error.
 192
 193 *objects_build_with_stringchecks*::
 194   Module 'ccan/str' is super difficult to detect errors debugging chain.
 195   *ccanlint* use with the module and see break!
 196
 197 *tests_exist*::
 198   You have CCAN module directory called 'test'. You have proof
 199   here. If there is no proof, *ccanlint* still offer make proof for
 200   you.
 201
 202 *tests_compile*::
 203   In 'test' which has four such tests, start with different
 204   name. 'run' compile the test files, but no link to the module, you
 205   '#include' to get the bits of the module. 'api' test compile and
 206   link with the module. 'compile-ok' as 'run' but only build.
 207   'compile-fail' compile, but when 'FAIL' set has to break or
 208   alert. This good for module supposed to warn.
 209
 210 *test_helpers_compile*::
 211   Other files 'test'? Compilation of links to all tests. Ask for help.
 212
 213 *tests_pass*::
 214   'run' and 'api' test happy departure. If not happy, offer debugger.
 215
 216 *tests_pass_valgrind*::
 217   *valgrind* the tool of all 'run' and 'api' slow test.  However, we
 218   found many errors! If *valgrind* test rest, '_info' have *ccanlint* section,
 219   make "tests_pass_valgrind test/TESTNAME:FAIL".  If required
 220   valgrind additional option, "tests_pass_valgrind test/TESTNAME:--option".
 221
 222 *tests_pass_valgrind_noleaks*::
 223   *valgrind* complain if the memory leak test. '_info' can also be disabled.
 224
 225 *tests_compile_coverage*::
 226   Compile 'run', 'api' test coverage. Fun if not here!
 227
 228 *tests_coverage*::
 229   Run tests again, find lines that never try! Half of the lines 1
 230   point 3/4 getting 2 points. Limit of 5 points, but the extra point
 231   for all lines of evidence.  Not win unless the module silly or use
 232   gimmick 'ccan/failtest'.
 233
 234 *reduce_features*::
 235   Code use 'HAVE_FEATURE' make special config.h turned off.  Not
 236   stupid like HAVE_BIG_ENDIAN though!
 237
 238 *depends_build_without_features*::
 239   Make modules CCAN need. config.h but not more features.
 240
 241 *objects_build_without_features*::
 242   Make the module again, but not more features.
 243
 244 *tests_helpers_compile_without_features*::
 245   Helpers do try again, but not more features.
 246
 247 *tests_compile_without_features*::
 248   Collect the tests again, but not more features.
 249
 250 *tests_pass_without_features*:
 251   Run tests again, but not more features.
 252
 253 BUGS
 254 ----
 255 *ccanlint* rapid change. The bad man, bad page.
 256
 257 AUTHOR
 258 ------
 259 Rusty Russell wrote *ccanlint*. Helping others, but most break Rusty.
 260
 261
 262 RESOURCES
 263 ---------
 264 Main web site: http://ccodearchive.net/
 265
 266 Wiki: https://github.com/rustyrussell/ccan/wiki/
 267
 268 COPYING
 269 -------
 270 This program is free software; you can redistribute it and/or modify it
 271 under the terms of the GNU General Public License as published by the Free
 272 Software Foundation; either version 2 of the License, or (at your option)
 273 any later version.