Annotation of embedaddon/curl/docs/CHECKSRC.md, revision 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.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to CHECKSRC.md CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs