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