1KRAZY2(1) User Contributed Perl Documentation KRAZY2(1)
2
6 krazy2 - Sanity checks KDE source code.
7
9 krazy2 [OPTIONS] [FILES]
10
12 krazy2 scans KDE source code looking for issues that should be fixed
13 for reasons of policy, good coding practice, optimization, or any other
14 good reason. In typical use, krazy2 simply counts up the issues and
15 provides the line numbers where those issues occurred in each file
16 processed. With the verbose option, the offending content will be
17 printed as well.
18 krazy2 uses "checker programs" which are small plugin programs to do
20 the real work of the scanning. It is easy to write your own plugins
21 (see PLUGINS) and tell krazy2 how to use them (see ENVIRONMENT).
22 A list of FILES to process is either specified on the command line or
24 read from standard input if the first file name is "-", in which case 1
25 file per line is expected. Blank lines and lines starting with a '#'
26 are ignored when reading the file list from standard input.
27
29 --help
30 Print help message and exit.
31 --version
33 Print version information and exit.
34 --list
36 Print a list of all available checker programs and exit.
37 --list-types
39 Print a list of all the supported file types and exit.
40 --list-sets
42 Print a list of all the checker sets and exit.
43 --list-set <set>
45 Print the list of available checkers for the specified set and
46 exit.
47 --priority <low|normal|high|important|all>
49 Tell each checker program to report issues with the specified
50 priority only. This option is useful to help put issues into "fix-
51 first" order.
52 Supported priorites are:
54 low -> print low priority issues only
55 normal -> print normal priority issues only
56 high -> print high priority issues only
57 important -> print issues with normal or high priority
58 all -> print all issues (default)
59 --strict <normal|super|all>
61 Tell each checker program to report issues match the strictness
62 level only. Use this option to help filter out issues of less
63 importance.
64 Support strictness levels are:
66 normal -> print non-super strict issues only
67 super -> print super strict issues only
68 all -> print all issues (default)
69 --explain
71 For each checker program, if any issues are found, print an
72 explanation of the problem along with solving instructions. May be
73 used in conjunction with the --list option to provide a more
74 detailed description of the checker programs.
75 --ignorerc
77 Ignore .krazy files.
78 --config <krazyrc>
80 Read settings from the specified krazyrc configuration file only.
81 All other configuration files will be ignored, including those
82 found in the user's home directory or in the current working
83 directory.
84 --dry-run
86 With this option the checker programs aren't run; instead, the
87 command line for each check that would be run is printed.
88 --check <prog[,prog1,prog2,...,progN]>
90 Run the specified checker program(s) only. You may not combine
91 this option with --check-sets.
92 Use the --list option to show the list of available checkers.
94 --check-sets <set[,set1,set2,...,setN]>
96 Run the checker programs belonging to the specified set(s) only.
97 You may not combine this option with --check.
98 Use the --list-sets option to see the list of available check sets
100 and programs.
101 --exclude <prog[,prog1,prog2,...,progN]>
103 Do NOT run the specified checker program(s).
104 Use the --list option to show the list of available checkers.
106 --extra <prog[,prog1,prog2,...,progN]>
108 Add the specified "extra" program(s) to the list of checkers to
109 run.
110 Use the --list option to show the list of available "extra"
112 checkers; they will be marked with the tag [EXTRA] by the checker
113 description line.
114 --types <type[,type1,type2,...,typeN]>
116 Check the specified file type(s) only.
117 --exclude-types <type[,type1,type2,...,typeN]>
119 Do NOT check the specified file type(s).
120 --export <text|textlist|textedit|xml>
122 Output in one of the following formats:
123 text (default)
124 textlist -> plain old text, 1 offending file-per-line
125 textedit -> text formatted for IDEs, 1 issue-per-line
126 the format is: file:line-number:issue
127 xml -> XML formatted
128 --title
130 Give the output report a project title.
131 --cms
133 An acronym for "component/module/subdir". Used to write the
134 breadcrumbs line in the xml export. Must be a slash-delimited
135 triple containing the component, module, and subdir which is being
136 scanned.
137 --rev
139 Subversion revision number to be printed on the output report, if
140 provided.
141 --brief
143 Only print the output for checkers that have at least 1 issue.
144 --no-brief
146 Print the result of all checks i.e, the opposite of --brief. This
147 is the default output setting.
148 --quiet
150 Suppress all output messages.
151 --verbose
153 Print the offending content for each file processed
154
156 Print a list of all available checker programs along with a short
157 description:
158 % krazy2 --list
159 Available KDE source code sanitizer checks:
161 For c++ file types ==
162 captruefalse: Check for FALSE macro
163 captrue: Check for TRUE macro
164 copyright: Check for an acceptable copyright
165 doublequote_char: Check for adding single char string to a QString
166 license: Check for an acceptable license
167 nullstrassign: Check for assignments to QString::null
168 nullstrcompare: Check for compares to QString::null
169 qmax: Check for QMAX macros
170 qmin: Check for QMIN macros
171 For desktop file types ==
173 contractions: Check for contractions in strings
174 endswithnewline: Check that file ends with a newline
175 For designer file types ==
177 endswithnewline: Check that file ends with a newline
178 i18ncheckarg: Check validity of i18n calls
179 spelling: Check for spelling errors
180 Run all checker programs on a file:
182 % krazy2 fred.cc
183 =>c++/captruefalse test in-progress.done
185 =>c++/captrue test in-progress.done
186 =>c++/copyright test in-progress.done
187 =>c++/doublequote_chars test in-progress.done
188 =>c++/license test in-progress.done
189 =>c++/nullstrassign test in-progress.done
190 =>c++/nullstrcompare test in-progress.done
191 =>c++/qmax test in-progress.done
192 =>c++/qmin test in-progress.done
193 No Issues Found!
195 1. Check for FALSE macro... okay!
197 2. Check for TRUE macro... okay!
199 3. Check for an acceptable copyright... okay!
201 4. Check for adding single char string to a QString... okay!
203 5. Check for an acceptable license... okay!
205 6. Check for assignments to QString::null... okay!
207 7. Check for compares to QString::null... okay!
209 8. Check for QMAX macros... okay!
211 9. Check for QMIN macros... okay!
213 Run all checker programs except license and copyright the .cpp files in
215 the current working directory:
216 % krazy2 --exclude license,copyright *.cpp
217 Run the "captruefalse" checker programs on the *.cpp, *.cc, and *.h
219 found in the current working directory tree, printing explanations if
220 any issues are encountered:
221 % find . -name "*.cpp" -o -name "*.cc" -o -name "*.h" | \
222 xargs krazy2 --check captruefalse --explain
223 =>c++/captruefalse test in-progress........done
225 Total Issues = 10
227 1. Check for FALSE macro... OOPS! 232 issues found!
229 ./fred.h: line#176 (1)
230 ./fredmsg.h: line#41,54 (2)
231 ./fred.cpp.cpp: line#436,530,702,724,1030,1506,1525 (7)
232 The FALSE macro is obsolete and should be replaced by the
234 false (all lower case) macro.
235 Run all the checker programs on desktop files only:
237 % krazy2 --types=desktop *
238
240 The Krazy plugins support the following list of in-code directives:
241 Note that these directives must be C++ style comments that can be put
243 anywhere in the file desired (except embedded within C-style comments).
244 //krazy:skip
246 no krazy2 tests will run on this file.
247 //krazy:excludeall=<name1[,name2,...,nameN]>
249 the krazy2 tests name1, etc will not be run on this file.
250 //krazy:exclude=<name1[,name2,...,nameN]>
252 the krazy2 tests name1, etc. will not be run on the line where
253 this directive is found.
254 //krazy:cond=<name1[,name2,...,nameN]>
256 the krazy2 tests name1, etc. will not be run starting on the line
257 where this directive is found. Running of the specified tests will
258 remain interruptted until a line matching
259 //krazy:endcond=<name1[,name2,...,nameN]>
261 is encountered
263
265 Write your own plugin:
266 Copy TEMPLATE.pl to your new file.
268 Make the new file executable "chmod +x file".
269 Move the new file into the installed plugins directory, or create your
270 own krazy-plugins directory and add it to the $KRAZY_PLUGIN_PATH
271 environment (see ENVIRONMENT).
272 You may write the plugin in the language of your choice, but it must
274 follow these rules:
275 1. must accept the following optional command line args:
277 --help: print one-line help message and exit
278 --version: print one-line version information and exit
279 --priority: report issues of the specified priority only
280 --strict: report issues with the specified strictness level only
281 --explain: print an explanation with solving instructions
282 --installed file is to be installed
283 --quiet: suppress all output messages
284 --verbose: print the offending content
285 2. must require one command line argument which is the file to test.
287 3. must exit with status 0, and print "okay" if the file passes the
288 test.
289 4. must exit with non-zero status if issues are encountered.
290 5. if issues are encountered, the final line printed should be
291 "ISSUES=N", where N is the total number of issues found. Krazy2
292 assumes this is the last line of output, even if the plugin prints more
293 information after the "ISSUES=N" line.
294 6. must print a string to standard output showing line number(s) that
295 fail the test.
296 7. the plugin should be a quick test of a source code file.
297 8. the --explain option must print an explanation of why the offending
298 code is a problem, along with instructions on how to fix the code.
299 9. finally, and importantly, the plugin must eliminate false positives
300 as much as possible.
301
303 KRAZY_PLUGIN_PATH - this is a colon-separated list of paths which is
304 searched when locating plugins. By default, plugins are searched for in
305 the path $TOP/lib/krazy2/krazy-plugins:krazy-plugins.
306 KRAZY_EXTRA_PATH - this is a colon-separated list of paths which is
308 searched when locating "extra" plugins. By default, the "extras" are
309 searched for in the path $TOP/lib/krazy2/krazy-extras:krazy-extras.
310 KRAZY_SET_PATH - this is a colon-separated list of paths which is
312 searched when locating checker sets. By default, the sets are searched
313 for in the path $TOP/lib/krazy2/krazy-sets:krazy-sets.
314 where $TOP is the top-level installation directory (eg. /usr/local,
316 /usr/local/Krazy2)
317 KRAZY_STYLE_CPPSTYLE - tells the "style" checker to follow the
319 guidelines of the specified C++-style. Note: Krazy uses a heuristic to
320 decide what type of C++-style to check against. That heuristic isn't
321 very smart; so use this setting to enforce the C++-style.
322 C++-style must be one of the following:
324 "kde" (default), see
326 http://techbase.kde.org/Policies/Kdelibs_Coding_Style
327 "pim" kdepim style, see
329 http://pim.kde.org/development/coding-korganizer.php
330 KRAZY_STYLE_OFFSET - tells the "style" checker to check for a basic
332 indentation level, usually a small integer like 2 or 4. This value
333 overrides the offset provided as part of the C++-style (see
334 KRAZY_STYLE_CPPSTYLE).
335 KRAZY_STYLE_LINEMAX - tells the "style" checker to check for lines
337 longer than this number of characters. The default is unlimited
338 length.
339
341 In normal operation, krazy2 exits with a status equal to the total
342 number of issues encountered during processing.
343 If a command line option was incorrectly provided, krazy2 exits with
345 status=1.
346 If krazy2 was envoked with the --help, --version, --list, --list-types,
348 --list-sets or --list-set options it will exit with status=0.
349
351 Copyright (c) 2005-2013 by Allen Winter <winter@kde.org>
352 This program is free software; you can redistribute it and/or modify it
354 under the terms of the GNU General Public License as published by the
355 Free Software Foundation; either version 2 of the License, or (at your
356 option) any later version.
357 This program is distributed in the hope that it will be useful, but
359 WITHOUT ANY WARRANTY; without even the implied warranty of
360 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
361 General Public License for more details.
362 You should have received a copy of the GNU General Public License along
364 with this program; if not, write to the Free Software Foundation, Inc.,
365 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
366
368 .krazy (see krazyrc(3))
369 krazy2 first parses a .krazy file found in the user's home directory,
371 if such a file exists.
372 Next, krazy2 searches up the current working directory tree for a
374 project specific .krazy file. If one is found, its settings are merged
375 with (or override) those already found from $HOME/.krazy.
376 [For example, if the current working dir is
378 /my/kde/trunk/KDE/kdepimlibs/kcal/versit, then krazy2 will look for
379 /my/kde/trunk/KDE/kdepimlibs/kcal/.krazy, since kcal is the project
380 within the kdepimlibs module.]
381 If krazy2 determines that the current working directory is not located
383 within the KDE directory structure, then it simply reads the settings
384 from the .krazy file found in the current working directory, if such a
385 file exists.
386 If krazy2 determines that the current working directory is located
388 within the KDE directory structure but above a project subdir (eg.
389 trunk/KDE/kdepim), then it assumes no project specific /.krazy file.
390
392 krazyrc(3), krazy2all(1), krazy2xml(1)
393 Ben Meyer's kdetestscripts - Automated scripts are to catch problems in
395 KDE, <http://websvn.kde.org/trunk/playground/base/kdetestscripts>.
396 flawfinder - Examines source code looking for security weaknesses,
398 <http://www.dwheeler.com/flawfinder>.
399
401 Allen Winter, <winter@kde.org>
402perl v5.32.1 2021-01-26 KRAZY2(1)