Linux Certif

Toute la documentation sur la certification Linux LPI

krazy2

NAME

krazy2 - Sanity checks KDE source code.

SYNOPSIS

krazy2 [OPTIONS] [FILES]

DESCRIPTION

krazy2 scans KDE source code looking for issues that should be fixed for reasons of policy, good coding practice, optimization, or any other good reason. In typical use, krazy2 simply counts up the issues and provides the line numbers where those issues occurred in each file processed. With the verbose option, the offending content will be printed as well.

krazy2 uses ``checker programs'' which are small plugin programs to do the real work of the scanning. It is easy to write your own plugins (see PLUGINS) and tell krazy2 how to use them (see ENVIRONMENT).

A list of FILES to process is either specified on the command line or read from standard input if the first file name is ``-'', in which case 1 file per line is expected. Blank lines and lines starting with a '#' are ignored when reading the file list from standard input.

OPTIONS

--help

Print help message and exit.

--version

Print version information and exit.

--list

Print a list of all available checker programs and exit.

--list-types

Print a list of the support file types and exit.

--priority <low|normal|high|important|all>

Tell each checker program to report issues with the specified priority only. This option is useful to help put issues into ``fix-first'' order.

Supported priorites are:
     low -> print low priority issues only
     normal -> print normal priority issues only
     high -> print high priority issues only
     important -> print issues with normal or high priority
     all -> print all issues (default)

--strict <normal|super|all>

Tell each checker program to report issues match the strictness level only. Use this option to help filter out issues of less importance.

Support strictness levels are:
     normal -> print non-super strict issues only
     super -> print super strict issues only
     all -> print all issues (default)

--explain

For each checker program, if any issues are found, print an explanation of the problem along with solving instructions. May be used in conjunction with the --list option to provide a more detailed description of the checker programs.

--ignorerc

Ignore .krazy files.

--dry-run

With this option the checker programs aren't run; instead, the command line for each check that would be run is printed.

--check <prog[,prog1,prog2,...,progN]>

Run the specified checker program(s) only.

--exclude <prog[,prog1,prog2,...,progN]>

Do NOT run the specified checker program(s).

--extra <prog[,prog1,prog2,...,progN]>

Add the specified ``extra'' program(s) to the list of checkers to run. Use the --list option to show the list of available ``extra'' checkers; they will be marked with the tag [EXTRA] by the checker description line.

--export <text|textlist|textedit|ebn|ebnlxr|html|htmllxr|xml>

Output in one of the following formats:
     text (default)
     textlist -> plain old text, 1 offending file-per-line
     textedit -> text formatted for IDEs, 1 issue-per-line
                 the format is:  file:line-number:issue
     ebn -> English Breakfast Network style
     ebnlxr -> English Breakfast Network style, with links to lxr.kde.org
     html -> plain old html
     htmllxr -> plain old html, with links to lxr.kde.org
     xml -> XML formatted

--title

Give the output report a project title.

--cms

An acronym for ``component/module/subdir''. Used to write the breadcrumbs line in the ebn and html export. Must be a slash-delimited triple containing the component, module, and subdir which is being scanned.

--rev

Subversion revision number to be printed on the output report, if provided.

--brief

Only print the output for checkers that have at least 1 issue.

--quiet

Suppress all output messages.

--verbose

Print the offending content for each file processed

EXAMPLES

Print a list of all available checker programs along with a short description:

  % krazy2 --list
 
  Available KDE source code sanitizer checks:
  For c++ file types ==
         capfalse: Check for FALSE macro
           captrue: Check for TRUE macro
         copyright: Check for an acceptable copyright
  doublequote_char: Check for adding single char string to a QString
           license: Check for an acceptable license
     nullstrassign: Check for assignments to QString::null
    nullstrcompare: Check for compares to QString::null
              qmax: Check for QMAX macros
              qmin: Check for QMIN macros
 
 

For desktop file types ==
      contractions: Check for contractions in strings
   endswithnewline: Check that file ends with a newline

For designer file types ==
   endswithnewline: Check that file ends with a newline
      i18ncheckarg: Check validity of i18n calls
          spelling: Check for spelling errors

Run all checker programs on a file:

  % krazy2 fred.cc
 
  =>c++/capfalse test in-progress.done
  =>c++/captrue test in-progress.done
  =>c++/copyright test in-progress.done
  =>c++/doublequote_chars test in-progress.done
  =>c++/license test in-progress.done
  =>c++/nullstrassign test in-progress.done
  =>c++/nullstrcompare test in-progress.done
  =>c++/qmax test in-progress.done
  =>c++/qmin test in-progress.done
 
  No Issues Found!
 
  1. Check for FALSE macro... okay!
 
  2. Check for TRUE macro... okay!
 
  3. Check for an acceptable copyright... okay!
 
  4. Check for adding single char string to a QString... okay!
 
  5. Check for an acceptable license... okay!
 
  6. Check for assignments to QString::null... okay!
 
  7. Check for compares to QString::null... okay!
 
  8. Check for QMAX macros... okay!
 
  9. Check for QMIN macros... okay!
 
 

Run all checker programs except license and copyright the .cpp files in the current working directory:

  % krazy2 --exclude license,copyright *.cpp
 
 

Run the "capfalse" checker programs on the *.cpp, *.cc, and *.h found in the current working directory tree, printing explanations if any issues are encountered:

  % find . -name "*.cpp" -o -name "*.cc" -o -name "*.h" | \
  xargs krazy2 --check capfalse --explain
 
  =>c++/capfalse test in-progress........done
 
  Total Issues = 10
 
  1. Check for FALSE macro... OOPS! 232 issues found!
         ./fred.h: line#176 (1)
         ./fredmsg.h: line#41,54 (2)
         ./fred.cpp.cpp: line#436,530,702,724,1030,1506,1525 (7)
 
         The FALSE macro is obsolete and should be replaced by the
         false (all lower case) macro.
 
 

DIRECTIVES

The Krazy plugins support the following list of in-code directives:

//krazy:skip

  no krazy2 tests will run on this file.
 
 

//krazy:excludeall=<name1[,name2,...,nameN]>

  the krazy2 tests name1, etc will not be run on this file.
 
 

//krazy:exclude=<name1[,name2,...,nameN]>

  the krazy2 tests name1, etc. will not be run on the line where
  this directive is found.
 
 

Note that these directives must be C++ style comments that can be put anywhere in the file desired (except embedded within C-style comments).

PLUGINS

Write your own plugin:

Copy TEMPLATE.pl to your new file.

Make the new file executable "chmod +x file".

Move the new file into the installed plugins directory, or create your own krazy-plugins directory and add it to the $KRAZY_PLUGIN_PATH environment (see ENVIRONMENT).

You may write the plugin in the language of your choice, but it must follow these rules:

1. must accept the following optional command line args:

  --help:     print one-line help message and exit
  --version:  print one-line version information and exit
  --priority: report issues of the specified priority only
  --strict:   report issues with the specified strictness level only
  --explain:  print an explanation with solving instructions
  --installed file is to be installed
  --quiet:    suppress all output messages
  --verbose:  print the offending content
 
 

2. must require one command line argument which is the file to test.

3. must exit with status 0, and print "okay" if the file passes the test.

4. must exit with non-zero status (=total issues) if issues are encountered.

5. must print a string to standard output showing line number(s) that fail the test.

6. the plugin should be a quick test of a source code file.

7. the --explain option must print an explanation of why the offending code is a problem, along with instructions on how to fix the code.

8. finally, and importantly, the plugin must eliminate false positives as much as possible.

ENVIRONMENT

KRAZY_PLUGIN_PATH - this is a colon-separated list of paths which is searched when locating plugins. By default, plugins are searched for in the path $TOP/lib/krazy2/krazy-plugins:krazy-plugins.

KRAZY_EXTRA_PATH - this is a colon-separated list of paths which is searched when locating ``extra'' plugins. By default, the ``extras'' are searched for in the path $TOP/lib/krazy2/krazy-extras:krazy-extras.

where $TOP is the top-level installation directory (eg. /usr/local, /usr/local/Krazy2)

EXIT STATUS

In normal operation, krazy2 exits with a status equal to the total number of issues encountered during processing.

If a command line option was incorrectly provided, krazy2 exits with status=1.

If krazy2 was envoked with the --help, --version, --list or --list-types options it will exit with status=0.

COPYRIGHT

Copyright (c) 2005-2008 by Allen Winter <winter@kde.org>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

FILES

.krazy (see krazyrc(5))

krazy2 looks up the current working directory tree for a .krazy file in the project subdirectory. Only .krazy files found at the project subdirectory level are read.

For example, if the current working dir is /my/kde/trunk/KDE/kdepimlibs/kcal/versit, then krazy2 will look for /my/kde/trunk/KDE/kdepimlibs/kcal/.krazy, since kcal is the project within the kdepimlibs module.

If the current working dir is not within a KDE module, or if the current working dir is above a project subdir, then a .krazy file will not be read.

SEE ALSO

krazyrc(5), krazy2all(1), krazy2ebn(1)

Ben Meyer's kdetestscripts - Automated scripts are to catch problems in KDE, <http://websvn.kde.org/trunk/playground/base/kdetestscripts>.

flawfinder - Examines source code looking for security weaknesses, <http://www.dwheeler.com/flawfinder>.

AUTHORS

Allen Winter, <winter@kde.org>