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