1KRAZY2(1)             User Contributed Perl Documentation            KRAZY2(1)
2
3
4

NAME

6       krazy2 - Sanity checks KDE source code.
7

SYNOPSIS

9       krazy2 [OPTIONS] [FILES]
10

DESCRIPTION

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

OPTIONS

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       --list-set <set>
45           Print the list of available checkers for the specified set and
46           exit.
47
48       --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
53           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
60       --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
65           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
70       --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
76       --ignorerc
77           Ignore .krazy files.
78
79       --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
85       --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
89       --check <prog[,prog1,prog2,...,progN]>
90           Run the specified checker program(s) only.  You may not combine
91           this option with --check-sets.
92
93           Use the --list option to show the list of available checkers.
94
95       --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
99           Use the --list-sets option to see the list of available check sets
100           and programs.
101
102       --exclude <prog[,prog1,prog2,...,progN]>
103           Do NOT run the specified checker program(s).
104
105           Use the --list option to show the list of available checkers.
106
107       --extra <prog[,prog1,prog2,...,progN]>
108           Add the specified "extra" program(s) to the list of checkers to
109           run.
110
111           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
115       --types <type[,type1,type2,...,typeN]>
116           Check the specified file type(s) only.
117
118       --exclude-types <type[,type1,type2,...,typeN]>
119           Do NOT check the specified file type(s).
120
121       --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
129       --title
130           Give the output report a project title.
131
132       --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
138       --rev
139           Subversion revision number to be printed on the output report, if
140           provided.
141
142       --brief
143           Only print the output for checkers that have at least 1 issue.
144
145       --no-brief
146           Print the result of all checks i.e, the opposite of --brief.  This
147           is the default output setting.
148
149       --quiet
150           Suppress all output messages.
151
152       --verbose
153           Print the offending content for each file processed
154

EXAMPLES

156       Print a list of all available checker programs along with a short
157       description:
158            % krazy2 --list
159
160            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
172           For desktop file types ==
173                 contractions: Check for contractions in strings
174              endswithnewline: Check that file ends with a newline
175
176           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
181       Run all checker programs on a file:
182            % krazy2 fred.cc
183
184            =>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
194            No Issues Found!
195
196            1. Check for FALSE macro... okay!
197
198            2. Check for TRUE macro... okay!
199
200            3. Check for an acceptable copyright... okay!
201
202            4. Check for adding single char string to a QString... okay!
203
204            5. Check for an acceptable license... okay!
205
206            6. Check for assignments to QString::null... okay!
207
208            7. Check for compares to QString::null... okay!
209
210            8. Check for QMAX macros... okay!
211
212            9. Check for QMIN macros... okay!
213
214       Run all checker programs except license and copyright the .cpp files in
215       the current working directory:
216            % krazy2 --exclude license,copyright *.cpp
217
218       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
224            =>c++/captruefalse test in-progress........done
225
226            Total Issues = 10
227
228            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
233                   The FALSE macro is obsolete and should be replaced by the
234                   false (all lower case) macro.
235
236       Run all the checker programs on desktop files only:
237            % krazy2 --types=desktop *
238

IN-CODE DIRECTIVES

240       The Krazy plugins support the following list of in-code directives:
241
242       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
245       //krazy:skip
246            no krazy2 tests will run on this file.
247
248       //krazy:excludeall=<name1[,name2,...,nameN]>
249            the krazy2 tests name1, etc will not be run on this file.
250
251       //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
255       //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
260             //krazy:endcond=<name1[,name2,...,nameN]>
261
262             is encountered
263

PLUGINS

265       Write your own plugin:
266
267        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
273       You may write the plugin in the language of your choice, but it must
274       follow these rules:
275
276       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
286       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

ENVIRONMENT

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
307       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
311       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
315       where $TOP is the top-level installation directory (eg. /usr/local,
316       /usr/local/Krazy2)
317
318       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
323       C++-style must be one of the following:
324
325         "kde" (default), see
326         http://techbase.kde.org/Policies/Kdelibs_Coding_Style
327
328         "pim" kdepim style, see
329         http://pim.kde.org/development/coding-korganizer.php
330
331       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
336       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

EXIT STATUS

341       In normal operation, krazy2 exits with a status equal to the total
342       number of issues encountered during processing.
343
344       If a command line option was incorrectly provided, krazy2 exits with
345       status=1.
346
347       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
353       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
358       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
363       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

FILES

368       .krazy (see krazyrc(3))
369
370       krazy2 first parses a .krazy file found in the user's home directory,
371       if such a file exists.
372
373       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
377       [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
382       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
387       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

SEE ALSO

392       krazyrc(3), krazy2all(1), krazy2xml(1)
393
394       Ben Meyer's kdetestscripts - Automated scripts are to catch problems in
395       KDE, <http://websvn.kde.org/trunk/playground/base/kdetestscripts>.
396
397       flawfinder - Examines source code looking for security weaknesses,
398       <http://www.dwheeler.com/flawfinder>.
399

AUTHORS

401       Allen Winter, <winter@kde.org>
402
403
404
405perl v5.38.0                      2023-07-20                         KRAZY2(1)
Impressum