Return to CHECKSRC.md CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs

curl

    1: # checksrc
    2: 
    3: This is the tool we use within the curl project to scan C source code and
    4: check that it adheres to our [Source Code Style guide](CODE_STYLE.md).
    5: 
    6: ## Usage
    7: 
    8:     checksrc.pl [options] [file1] [file2] ...
    9: 
   10: ## Command line options
   11: 
   12: `-W[file]` whitelists that file and excludes it from being checked. Helpful
   13: when, for example, one of the files is generated.
   14: 
   15: `-D[dir]` directory name to prepend to file names when accessing them.
   16: 
   17: `-h` shows the help output, that also lists all recognized warnings
   18: 
   19: ## What does checksrc warn for?
   20: 
   21: checksrc does not check and verify the code against the entire style guide,
   22: but the script is instead an effort to detect the most common mistakes and
   23: syntax mistakes that contributors make before they get accustomed to our code
   24: style. Heck, many of us regulars do the mistakes too and this script helps us
   25: keep the code in shape.
   26: 
   27:     checksrc.pl -h
   28: 
   29: Lists how to use the script and it lists all existing warnings it has and
   30: problems it detects. At the time of this writing, the existing checksrc
   31: warnings are:
   32: 
   33: - `ASSIGNWITHINCONDITION`: Assignment within a conditional expression. The
   34:   code style mandates the assignment to be done outside of it.
   35: 
   36: - `ASTERISKNOSPACE`: A pointer was declared like `char* name` instead of the more
   37:    appropriate `char *name` style. The asterisk should sit next to the name.
   38: 
   39: - `ASTERISKSPACE`: A pointer was declared like `char * name` instead of the
   40:    more appropriate `char *name` style. The asterisk should sit right next to
   41:    the name without a space in between.
   42: 
   43: - `BADCOMMAND`: There's a bad !checksrc! instruction in the code. See the
   44:    **Ignore certain warnings** section below for details.
   45: 
   46: - `BANNEDFUNC`: A banned function was used. The functions sprintf, vsprintf,
   47:    strcat, strncat, gets are **never** allowed in curl source code.
   48: 
   49: - `BRACEELSE`: '} else' on the same line. The else is supposed to be on the
   50:   following line.
   51: 
   52: - `BRACEPOS`: wrong position for an open brace (`{`).
   53: 
   54: - `COMMANOSPACE`: a comma without following space
   55: 
   56: - `COPYRIGHT`: the file is missing a copyright statement!
   57: 
   58: - `CPPCOMMENTS`: `//` comment detected, that's not C89 compliant
   59: 
   60: - `FOPENMODE`: `fopen()` needs a macro for the mode string, use it
   61: 
   62: - `INDENTATION`: detected a wrong start column for code. Note that this
   63:    warning only checks some specific places and will certainly miss many bad
   64:    indentations.
   65: 
   66: - `LONGLINE`: A line is longer than 79 columns.
   67: 
   68: - `MULTISPACE`: Multiple spaces were found where only one should be used.
   69: 
   70: - `NOSPACEEQUALS`: An equals sign was found without preceding space. We prefer
   71:   `a = 2` and *not* `a=2`.
   72: 
   73: - `OPENCOMMENT`: File ended with a comment (`/*`) still "open".
   74: 
   75: - `PARENBRACE`: `){` was used without sufficient space in between.
   76: 
   77: - `RETURNNOSPACE`: `return` was used without space between the keyword and the
   78:    following value.
   79: 
   80: - `SEMINOSPACE`: There was no space (or newline) following a semicolon.
   81: 
   82: - `SIZEOFNOPAREN`: Found use of sizeof without parentheses. We prefer
   83:   `sizeof(int)` style.
   84: 
   85: - `SNPRINTF` - Found use of `snprintf()`. Since we use an internal replacement
   86:    with a different return code etc, we prefer `msnprintf()`.
   87: 
   88: - `SPACEAFTERPAREN`: there was a space after open parenthesis, `( text`.
   89: 
   90: - `SPACEBEFORECLOSE`: there was a space before a close parenthesis, `text )`.
   91: 
   92: - `SPACEBEFORECOMMA`: there was a space before a comma, `one , two`.
   93: 
   94: - `SPACEBEFOREPAREN`: there was a space before an open parenthesis, `if (`,
   95:    where one was not expected
   96: 
   97: - `SPACESEMICOLON`: there was a space before semicolon, ` ;`.
   98: 
   99: - `TABS`: TAB characters are not allowed!
  100: 
  101: - `TRAILINGSPACE`: Trailing white space on the line
  102: 
  103: - `UNUSEDIGNORE`: a checksrc inlined warning ignore was asked for but not used,
  104:    that's an ignore that should be removed or changed to get used.
  105: 
  106: ### Extended warnings
  107: 
  108: Some warnings are quite computationally expensive to perform, so they are
  109: turned off by default. To enable these warnings, place a `.checksrc` file in
  110: the directory where they should be activated with commands to enable the
  111: warnings you are interested in. The format of the file is to enable one
  112: warning per line like so: `enable <EXTENDEDWARNING>`
  113: 
  114: Currently there is one extended warning which can be enabled:
  115: 
  116: - `COPYRIGHTYEAR`: the current changeset hasn't updated the copyright year in
  117:    the source file
  118: 
  119: ## Ignore certain warnings
  120: 
  121: Due to the nature of the source code and the flaws of the checksrc tool, there
  122: is sometimes a need to ignore specific warnings. checksrc allows a few
  123: different ways to do this.
  124: 
  125: ### Inline ignore
  126: 
  127: You can control what to ignore within a specific source file by providing
  128: instructions to checksrc in the source code itself. You need a magic marker
  129: that is `!checksrc!` followed by the instruction. The instruction can ask to
  130: ignore a specific warning N number of times or you ignore all of them until
  131: you mark the end of the ignored section.
  132: 
  133: Inline ignores are only done for that single specific source code file.
  134: 
  135: Example
  136: 
  137:     /* !checksrc! disable LONGLINE all */
  138: 
  139: This will ignore the warning for overly long lines until it is re-enabled with:
  140: 
  141:     /* !checksrc! enable LONGLINE */
  142: 
  143: If the enabling isn't performed before the end of the file, it will be enabled
  144: automatically for the next file.
  145: 
  146: You can also opt to ignore just N violations so that if you have a single long
  147: line you just can't shorten and is agreed to be fine anyway:
  148: 
  149:     /* !checksrc! disable LONGLINE 1 */
  150: 
  151: ... and the warning for long lines will be enabled again automatically after
  152: it has ignored that single warning. The number `1` can of course be changed to
  153: any other integer number. It can be used to make sure only the exact intended
  154: instances are ignored and nothing extra.
  155: 
  156: ### Directory wide ignore patterns
  157: 
  158: This is a method we've transitioned away from. Use inline ignores as far as
  159: possible.
  160: 
  161: Make a `checksrc.whitelist` file in the directory of the source code with the
  162: false positive, and include the full offending line into this file.