KRAZY2(1)

📦
version 2.97 · 2 versions
, in fedora 43

💖 KRAZY2(1) 💖

User Contributed Perl Documentation — KRAZY2(1)

okay bestie, pull up a chair, grab a strawberry 🍓, because we're about to get so into it. this is krazy2, the KDE source code sanity-checker, and she is iconic, she is thorough, and she will absolutely read your code to filth (affectionately). 💅

✨ NAME ✨

krazy2 — Sanity checks KDE source code. fr fr. 🧚

🌈 SYNOPSIS 🌈

krazy2 [OPTIONS] [FILES]

🦋 DESCRIPTION 🦋

so krazy2 scans KDE source code looking for issues that should be fixed — for reasons of policy, good coding practice, optimization, or literally any other good reason. she's not judging, she's helping. 💖 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 — yes, she'll read your problematic lines OUT LOUD. 🙈

krazy2 uses "checker programs" which are small plugin programs that 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). lowkey a build-your-own-bestie situation. 🫶

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. no drama, no chaos, just vibes. ✨

👑 OPTIONS 👑

  • --help — Print help message and exit. your girl is here to help. 🎀
  • --version — Print version information and exit. who is she? 💅
  • --list — Print a list of all available checker programs and exit.
  • --list-types — Print a list of all the supported file types and exit.
  • --list-sets — Print a list of all the checker sets and exit.
  • --list-set <set> — Print the list of available checkers for the specified set 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. i.e. it's giving to-do list energy. 🗒️

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. she's not just gonna tell you what's wrong, she's gonna tell you why. 😭
  • --ignorerc — Ignore .krazy files. not me ignoring my own config… 💀
  • --config <krazyrc> — Read settings from the specified krazyrc configuration file only. All other configuration files will be ignored, including those found in the user's home directory or in the current working directory. she's monogamous to this one file, periodt. 💖
  • --dry-run — With this option the checker programs aren't run; instead, the command line for each check that would be run is printed. window shopping only, no purchasing. 🛍️
  • --check <prog[,prog1,prog2,...,progN]> — Run the specified checker program(s) only. You may not combine this option with --check-sets.

Use the --list option to show the list of available checkers.

  • --check-sets <set[,set1,set2,...,setN]> — Run the checker programs belonging to the specified set(s) only. You may not combine this option with --check.

Use the --list-sets option to see the list of available check sets and programs.

  • --exclude <prog[,prog1,prog2,...,progN]> — Do NOT run the specified checker program(s). blocking them, respectfully. 🙅‍♀️

Use the --list option to show the list of available checkers.

  • --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.

  • --types <type[,type1,type2,...,typeN]> — Check the specified file type(s) only.
  • --exclude-types <type[,type1,type2,...,typeN]> — Do NOT check the specified file type(s).
  • --export <text|textlist|textedit|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
xml -> XML formatted
  • --title — Give the output report a project title. slay, branded. 🎀
  • --cms — An acronym for "component/module/subdir". Used to write the breadcrumbs line in the xml 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. no news is good news. ✨
  • --no-brief — Print the result of all checks i.e, the opposite of --brief. This is the default output setting.
  • --quiet — Suppress all output messages. 🤫
  • --verbose — Print the offending content for each file processed. receipts. 🧾

🌸 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 ==
   captruefalse: 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++/captruefalse 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 "captruefalse" 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 captruefalse --explain

=>c++/captruefalse 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.

Run all the checker programs on desktop files only:

% krazy2 --types=desktop *

🧚 IN-CODE DIRECTIVES 🧚

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

Note that these directives must be C++ style comments that can be put anywhere in the file desired (except embedded within C-style comments). so don't be sneaky and hide them inside C-style comments, she WILL not see them. 😭
  • //krazy:skip — no krazy2 tests will run on this file. full skip, she's looking away. 🙈
  • //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.
  • //krazy:cond=<name1[,name2,...,nameN]> — the krazy2 tests name1, etc. will not be run starting on the line where this directive is found. Running of the specified tests will remain interruptted until a line matching
//krazy:endcond=<name1[,name2,...,nameN]>

is encountered

💜 PLUGINS 💜

Write your own plugin — yes, you, bestie, you can absolutely build your own. 🌈

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
  1. must require one command line argument which is the file to test.
  2. must exit with status 0, and print "okay" if the file passes the test.
  3. must exit with non-zero status if issues are encountered.
  4. if issues are encountered, the final line printed should be "ISSUES=N", where N is the total number of issues found. Krazy2 assumes this is the last line of output, even if the plugin prints more information after the "ISSUES=N" line.
  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 (aka the vibes your shell hands over) 🌍

These are the env vars krazy2 peeks at, bestie. Set them, don't set them, whatever — but here's the tea:

  • KRAZY_PLUGIN_PATH — a colon-separated list of paths that gets searched when it's out here locating plugins. By default, plugins get hunted down in the path $TOP/lib/krazy2/krazy-plugins:krazy-plugins.
  • KRAZY_EXTRA_PATH — same deal, colon-separated list of paths, but this one is for finding "extra" plugins. By default the "extras" live at $TOP/lib/krazy2/krazy-extras:krazy-extras.
  • KRAZY_SET_PATH — yep, colon-separated list of paths again, searched when locating checker sets. Default spot is $TOP/lib/krazy2/krazy-sets:krazy-sets.

And what's $TOP, you ask? 💅 It's the top-level installation directory — like /usr/local, /usr/local/Krazy2.

  • KRAZY_STYLE_CPPSTYLE — this one tells the "style" checker to follow the guidelines of whichever C++-style you name. ⚠️ Note: Krazy uses a heuristic to figure out what type of C++-style to check against. That heuristic is not very smart, bestie, not even a little. So use this setting to enforce the C++-style.

C++-style has to be one of these:

  • KRAZY_STYLE_OFFSET — tells the "style" checker to check for a basic indentation level, usually a small integer like 2 or 4. This value overrides the offset that came bundled with the C++-style (see KRAZY_STYLE_CPPSTYLE). 👑
  • KRAZY_STYLE_LINEMAX — tells the "style" checker to flag lines longer than this many characters. The default is unlimited length, so no cap, no limit, live your truth.

🚪 EXIT STATUS (how it says goodbye) 🚪

In normal operation, krazy2 exits with a status equal to the total number of issues encountered during processing. Yes, fr fr — the exit code is literally the receipts. 😭

  • If a command line option was incorrectly provided, krazy2 exits with status=1.
  • If krazy2 was invoked with the --help, --version, --list, --list-types, --list-sets or --list-set options, it will exit with status=0. ✨

Copyright (c) 2005-2013 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 (where it goes looking for your settings) 📁

Okay so here's the whole detective arc, step by step:

krazy2 first parses a .krazy file found in the user's home directory, if such a file exists. 🏠

Next, krazy2 searches up the current working directory tree for a project specific .krazy file. If one is found, its settings are merged with (or override) those already found from $HOME/.krazy.

[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 krazy2 determines that the current working directory is not located within the KDE directory structure, then it simply reads the settings from the .krazy file found in the current working directory, if such a file exists.

If krazy2 determines that the current working directory is located within the KDE directory structure but above a project subdir (eg. trunk/KDE/kdepim), then it assumes no project specific /.krazy file. 💀

👀 SEE ALSO 👀

💖 AUTHORS 💖

Allen Winter, <winter@kde.org>

and that's the whole page, bestie!! 🫶 this one shipped as perl v5.42.0, dated 2025-07-24, and it's KRAZY2(1) — go forth and let krazy2 read your .krazy files, mwah 💅✨

📦 where this page comes from