Return to CHECKSRC.md CVS log

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

Annotation of embedaddon/curl/docs/CHECKSRC.md, revision 1.1.1.1

1.1       misho       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.