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 --priority <low|normal|high|important|all>
45 Tell each checker program to report issues with the specified
46 priority only. This option is useful to help put issues into "fix-
47 first" order.
48 Supported priorites are:
50 low -> print low priority issues only
51 normal -> print normal priority issues only
52 high -> print high priority issues only
53 important -> print issues with normal or high priority
54 all -> print all issues (default)
55 --strict <normal|super|all>
57 Tell each checker program to report issues match the strictness
58 level only. Use this option to help filter out issues of less
59 importance.
60 Support strictness levels are:
62 normal -> print non-super strict issues only
63 super -> print super strict issues only
64 all -> print all issues (default)
65 --explain
67 For each checker program, if any issues are found, print an
68 explanation of the problem along with solving instructions. May be
69 used in conjunction with the --list option to provide a more
70 detailed description of the checker programs.
71 --ignorerc
73 Ignore .krazy files.
74 --config <krazyrc>
76 Read settings from the specified krazyrc configuration file only.
77 All other configuration files will be ignored, including those
78 found in the user's home directory or in the current working
79 directory.
80 --dry-run
82 With this option the checker programs aren't run; instead, the
83 command line for each check that would be run is printed.
84 --check <prog[,prog1,prog2,...,progN]>
86 Run the specified checker program(s) only. You may not combine
87 this option with --check-sets.
88 Use the --list option to show the list of available checkers.
90 --check-sets <set[,set1,set2,...,setN]>
92 Run the checker programs belonging to the specified set(s) only.
93 You may not combine this option with --check.
94 Use the --list-sets option to see the list of available check sets
96 and programs.
97 --exclude <prog[,prog1,prog2,...,progN]>
99 Do NOT run the specified checker program(s).
100 Use the --list option to show the list of available checkers.
102 --extra <prog[,prog1,prog2,...,progN]>
104 Add the specified "extra" program(s) to the list of checkers to
105 run.
106 Use the --list option to show the list of available "extra"
108 checkers; they will be marked with the tag [EXTRA] by the checker
109 description line.
110 --types <type[,type1,type2,...,typeN]>
112 Check the specified file type(s) only.
113 --exclude-types <type[,type1,type2,...,typeN]>
115 Do NOT check the specified file type(s).
116 --export <text|textlist|textedit|xml>
118 Output in one of the following formats:
119 text (default)
120 textlist -> plain old text, 1 offending file-per-line
121 textedit -> text formatted for IDEs, 1 issue-per-line
122 the format is: file:line-number:issue
123 xml -> XML formatted
124 --title
126 Give the output report a project title.
127 --cms
129 An acronym for "component/module/subdir". Used to write the
130 breadcrumbs line in the xml export. Must be a slash-delimited
131 triple containing the component, module, and subdir which is being
132 scanned.
133 --rev
135 Subversion revision number to be printed on the output report, if
136 provided.
137 --brief
139 Only print the output for checkers that have at least 1 issue.
140 --quiet
142 Suppress all output messages.
143 --verbose
145 Print the offending content for each file processed
146
148 Print a list of all available checker programs along with a short
149 description:
150 % krazy2 --list
151 Available KDE source code sanitizer checks:
153 For c++ file types ==
154 captruefalse: Check for FALSE macro
155 captrue: Check for TRUE macro
156 copyright: Check for an acceptable copyright
157 doublequote_char: Check for adding single char string to a QString
158 license: Check for an acceptable license
159 nullstrassign: Check for assignments to QString::null
160 nullstrcompare: Check for compares to QString::null
161 qmax: Check for QMAX macros
162 qmin: Check for QMIN macros
163 For desktop file types ==
165 contractions: Check for contractions in strings
166 endswithnewline: Check that file ends with a newline
167 For designer file types ==
169 endswithnewline: Check that file ends with a newline
170 i18ncheckarg: Check validity of i18n calls
171 spelling: Check for spelling errors
172 Run all checker programs on a file:
174 % krazy2 fred.cc
175 =>c++/captruefalse test in-progress.done
177 =>c++/captrue test in-progress.done
178 =>c++/copyright test in-progress.done
179 =>c++/doublequote_chars test in-progress.done
180 =>c++/license test in-progress.done
181 =>c++/nullstrassign test in-progress.done
182 =>c++/nullstrcompare test in-progress.done
183 =>c++/qmax test in-progress.done
184 =>c++/qmin test in-progress.done
185 No Issues Found!
187 1. Check for FALSE macro... okay!
189 2. Check for TRUE macro... okay!
191 3. Check for an acceptable copyright... okay!
193 4. Check for adding single char string to a QString... okay!
195 5. Check for an acceptable license... okay!
197 6. Check for assignments to QString::null... okay!
199 7. Check for compares to QString::null... okay!
201 8. Check for QMAX macros... okay!
203 9. Check for QMIN macros... okay!
205 Run all checker programs except license and copyright the .cpp files in
207 the current working directory:
208 % krazy2 --exclude license,copyright *.cpp
209 Run the "captruefalse" checker programs on the *.cpp, *.cc, and *.h
211 found in the current working directory tree, printing explanations if
212 any issues are encountered:
213 % find . -name "*.cpp" -o -name "*.cc" -o -name "*.h" | \
214 xargs krazy2 --check captruefalse --explain
215 =>c++/captruefalse test in-progress........done
217 Total Issues = 10
219 1. Check for FALSE macro... OOPS! 232 issues found!
221 ./fred.h: line#176 (1)
222 ./fredmsg.h: line#41,54 (2)
223 ./fred.cpp.cpp: line#436,530,702,724,1030,1506,1525 (7)
224 The FALSE macro is obsolete and should be replaced by the
226 false (all lower case) macro.
227 Run all the checker programs on desktop files only:
229 % krazy2 --types=desktop *
230
232 The Krazy plugins support the following list of in-code directives:
233 //krazy:skip
235 no krazy2 tests will run on this file.
236 //krazy:excludeall=<name1[,name2,...,nameN]>
238 the krazy2 tests name1, etc will not be run on this file.
239 //krazy:exclude=<name1[,name2,...,nameN]>
241 the krazy2 tests name1, etc. will not be run on the line where
242 this directive is found.
243 Note that these directives must be C++ style comments that can be put
245 anywhere in the file desired (except embedded within C-style comments).
246
248 Write your own plugin:
249 Copy TEMPLATE.pl to your new file.
251 Make the new file executable "chmod +x file".
252 Move the new file into the installed plugins directory, or create your
253 own krazy-plugins directory and add it to the $KRAZY_PLUGIN_PATH
254 environment (see ENVIRONMENT).
255 You may write the plugin in the language of your choice, but it must
257 follow these rules:
258 1. must accept the following optional command line args:
260 --help: print one-line help message and exit
261 --version: print one-line version information and exit
262 --priority: report issues of the specified priority only
263 --strict: report issues with the specified strictness level only
264 --explain: print an explanation with solving instructions
265 --installed file is to be installed
266 --quiet: suppress all output messages
267 --verbose: print the offending content
268 2. must require one command line argument which is the file to test.
270 3. must exit with status 0, and print "okay" if the file passes the
271 test.
272 4. must exit with non-zero status if issues are encountered.
273 5. if issues are encountered, the final line printed should be
274 "ISSUES=N", where N is the total number of issues found. Krazy2
275 assumes this is the last line of output, even if the plugin prints more
276 information after the "ISSUES=N" line.
277 6. must print a string to standard output showing line number(s) that
278 fail the test.
279 7. the plugin should be a quick test of a source code file.
280 8. the --explain option must print an explanation of why the offending
281 code is a problem, along with instructions on how to fix the code.
282 9. finally, and importantly, the plugin must eliminate false positives
283 as much as possible.
284
286 KRAZY_PLUGIN_PATH - this is a colon-separated list of paths which is
287 searched when locating plugins. By default, plugins are searched for in
288 the path $TOP/lib/krazy2/krazy-plugins:krazy-plugins.
289 KRAZY_EXTRA_PATH - this is a colon-separated list of paths which is
291 searched when locating "extra" plugins. By default, the "extras" are
292 searched for in the path $TOP/lib/krazy2/krazy-extras:krazy-extras.
293 KRAZY_SET_PATH - this is a colon-separated list of paths which is
295 searched when locating checker sets. By default, the sets are searched
296 for in the path $TOP/lib/krazy2/krazy-sets:krazy-sets.
297 where $TOP is the top-level installation directory (eg. /usr/local,
299 /usr/local/Krazy2)
300 KRAZY_STYLE_CPPSTYLE - tells the "style" checker to follow the
302 guidelines of the specified C++-style. Note: Krazy uses a heuristic to
303 decide what type of C++-style to check against. That heuristic isn't
304 very smart; so use this setting to enforce the C++-style.
305 C++-style must be one of the following:
307 "kde" (default), see
309 http://techbase.kde.org/Policies/Kdelibs_Coding_Style
310 "pim" kdepim style, see
312 http://pim.kde.org/development/coding-korganizer.php
313 KRAZY_STYLE_OFFSET - tells the "style" checker to check for a basic
315 indentation level, usually a small integer like 2 or 4. This value
316 overrides the offset provided as part of the C++-style (see
317 KRAZY_STYLE_CPPSTYLE).
318 KRAZY_STYLE_LINEMAX - tells the "style" checker to check for lines
320 longer than this number of characters. The default is 100 characters.
321
323 In normal operation, krazy2 exits with a status equal to the total
324 number of issues encountered during processing.
325 If a command line option was incorrectly provided, krazy2 exits with
327 status=1.
328 If krazy2 was envoked with the --help, --version, --list, --list-types,
330 or --list-sets options it will exit with status=0.
331
333 Copyright (c) 2005-2010 by Allen Winter <winter@kde.org>
334 This program is free software; you can redistribute it and/or modify it
336 under the terms of the GNU General Public License as published by the
337 Free Software Foundation; either version 2 of the License, or (at your
338 option) any later version.
339 This program is distributed in the hope that it will be useful, but
341 WITHOUT ANY WARRANTY; without even the implied warranty of
342 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
343 General Public License for more details.
344 You should have received a copy of the GNU General Public License along
346 with this program; if not, write to the Free Software Foundation, Inc.,
347 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
348
350 .krazy (see krazyrc(5))
351 krazy2 first parses a .krazy file found in the user's home directory,
353 if such a file exists.
354 Next, krazy2 searches up the current working directory tree for a
356 project specific .krazy file. If one is found, its settings are merged
357 with (or override) those already found from $HOME/.krazy.
358 [For example, if the current working dir is
360 /my/kde/trunk/KDE/kdepimlibs/kcal/versit, then krazy2 will look for
361 /my/kde/trunk/KDE/kdepimlibs/kcal/.krazy, since kcal is the project
362 within the kdepimlibs module.]
363 If krazy2 determines that the current working directory is not located
365 within the KDE directory structure, then it simply reads the settings
366 from the .krazy file found in the current working directory, if such a
367 file exists.
368 If krazy2 determines that the current working directory is located
370 within the KDE directory structure but above a project subdir (eg.
371 trunk/KDE/kdepim), then it assumes no project specific /.krazy file.
372
374 krazyrc(5), krazy2all(1), krazy2xml(1)
375 Ben Meyer's kdetestscripts - Automated scripts are to catch problems in
377 KDE, <http://websvn.kde.org/trunk/playground/base/kdetestscripts>.
378 flawfinder - Examines source code looking for security weaknesses,
380 <http://www.dwheeler.com/flawfinder>.
381
383 Allen Winter, <winter@kde.org>
384perl v5.12.2 2010-09-02 KRAZY2(1)