1# checksrc
2
3This is the tool we use within the curl project to scan C source code and
4check 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
13when, 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
21checksrc does not check and verify the code against the entire style guide,
22but the script is instead an effort to detect the most common mistakes and
23syntax mistakes that contributors make before they get accustomed to our code
24style. Heck, many of us regulars do the mistakes too and this script helps us
25keep the code in shape.
26
27    checksrc.pl -h
28
29Lists how to use the script and it lists all existing warnings it has and
30problems it detects. At the time of this writing, the existing checksrc
31warnings 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
108Some warnings are quite computationally expensive to perform, so they are
109turned off by default. To enable these warnings, place a `.checksrc` file in
110the directory where they should be activated with commands to enable the
111warnings you are interested in. The format of the file is to enable one
112warning per line like so: `enable <EXTENDEDWARNING>`
113
114Currently 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
121Due to the nature of the source code and the flaws of the checksrc tool, there
122is sometimes a need to ignore specific warnings. checksrc allows a few
123different ways to do this.
124
125### Inline ignore
126
127You can control what to ignore within a specific source file by providing
128instructions to checksrc in the source code itself. You need a magic marker
129that is `!checksrc!` followed by the instruction. The instruction can ask to
130ignore a specific warning N number of times or you ignore all of them until
131you mark the end of the ignored section.
132
133Inline ignores are only done for that single specific source code file.
134
135Example
136
137    /* !checksrc! disable LONGLINE all */
138
139This will ignore the warning for overly long lines until it is re-enabled with:
140
141    /* !checksrc! enable LONGLINE */
142
143If the enabling isn't performed before the end of the file, it will be enabled
144automatically for the next file.
145
146You can also opt to ignore just N violations so that if you have a single long
147line 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
152it has ignored that single warning. The number `1` can of course be changed to
153any other integer number. It can be used to make sure only the exact intended
154instances are ignored and nothing extra.
155
156### Directory wide ignore patterns
157
158This is a method we've transitioned away from. Use inline ignores as far as
159possible.
160
161Make a `checksrc.whitelist` file in the directory of the source code with the
162false positive, and include the full offending line into this file.
163