1KRAZY2(1) User Contributed Perl Documentation KRAZY2(1)
2
3
4
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
19 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
23 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
32 --version
33 Print version information and exit.
34
35 --list
36 Print a list of all available checker programs and exit.
37
38 --list-types
39 Print a list of all the supported file types and exit.
40
41 --list-sets
42 Print a list of all the checker sets and exit.
43
44 --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
49 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
56 --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
61 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
66 --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
72 --ignorerc
73 Ignore .krazy files.
74
75 --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
81 --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
85 --check <prog[,prog1,prog2,...,progN]>
86 Run the specified checker program(s) only. You may not combine
87 this option with --check-sets.
88
89 Use the --list option to show the list of available checkers.
90
91 --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
95 Use the --list-sets option to see the list of available check sets
96 and programs.
97
98 --exclude <prog[,prog1,prog2,...,progN]>
99 Do NOT run the specified checker program(s).
100
101 Use the --list option to show the list of available checkers.
102
103 --extra <prog[,prog1,prog2,...,progN]>
104 Add the specified "extra" program(s) to the list of checkers to
105 run.
106
107 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
111 --types <type[,type1,type2,...,typeN]>
112 Check the specified file type(s) only.
113
114 --exclude-types <type[,type1,type2,...,typeN]>
115 Do NOT check the specified file type(s).
116
117 --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
125 --title
126 Give the output report a project title.
127
128 --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
134 --rev
135 Subversion revision number to be printed on the output report, if
136 provided.
137
138 --brief
139 Only print the output for checkers that have at least 1 issue.
140
141 --quiet
142 Suppress all output messages.
143
144 --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
152 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
164 For desktop file types ==
165 contractions: Check for contractions in strings
166 endswithnewline: Check that file ends with a newline
167
168 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
173 Run all checker programs on a file:
174 % krazy2 fred.cc
175
176 =>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
186 No Issues Found!
187
188 1. Check for FALSE macro... okay!
189
190 2. Check for TRUE macro... okay!
191
192 3. Check for an acceptable copyright... okay!
193
194 4. Check for adding single char string to a QString... okay!
195
196 5. Check for an acceptable license... okay!
197
198 6. Check for assignments to QString::null... okay!
199
200 7. Check for compares to QString::null... okay!
201
202 8. Check for QMAX macros... okay!
203
204 9. Check for QMIN macros... okay!
205
206 Run all checker programs except license and copyright the .cpp files in
207 the current working directory:
208 % krazy2 --exclude license,copyright *.cpp
209
210 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
216 =>c++/captruefalse test in-progress........done
217
218 Total Issues = 10
219
220 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
225 The FALSE macro is obsolete and should be replaced by the
226 false (all lower case) macro.
227
228 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
234 //krazy:skip
235 no krazy2 tests will run on this file.
236
237 //krazy:excludeall=<name1[,name2,...,nameN]>
238 the krazy2 tests name1, etc will not be run on this file.
239
240 //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
244 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
250 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
256 You may write the plugin in the language of your choice, but it must
257 follow these rules:
258
259 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
269 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
290 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
294 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
298 where $TOP is the top-level installation directory (eg. /usr/local,
299 /usr/local/Krazy2)
300
301 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
306 C++-style must be one of the following:
307
308 "kde" (default), see
309 http://techbase.kde.org/Policies/Kdelibs_Coding_Style
310
311 "pim" kdepim style, see
312 http://pim.kde.org/development/coding-korganizer.php
313
314 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
319 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
326 If a command line option was incorrectly provided, krazy2 exits with
327 status=1.
328
329 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
335 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
340 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
345 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
352 krazy2 first parses a .krazy file found in the user's home directory,
353 if such a file exists.
354
355 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
359 [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
364 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
369 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
376 Ben Meyer's kdetestscripts - Automated scripts are to catch problems in
377 KDE, <http://websvn.kde.org/trunk/playground/base/kdetestscripts>.
378
379 flawfinder - Examines source code looking for security weaknesses,
380 <http://www.dwheeler.com/flawfinder>.
381
383 Allen Winter, <winter@kde.org>
384
385
386
387perl v5.12.2 2010-09-02 KRAZY2(1)