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