Fpsonar

fpSonar is a static analyzer (a "linter") for Object Pascal. It reads Free Pascal and Lazarus source and reports things that look wrong — risky patterns, portability traps, confusing names, style that does not match your conventions — without running the code**.**

You give it some source; it gives you back a list of issues. This page covers installing and using it; the rule pages listed under Rule reference explain the individual checks, each with an example fpSonar accepts and one it complains about.

The program

edit

fpSonar ships in the FPC source tree as utils/fpsonar. After building it, the binary is at:

bin/x86_64-linux/fpsonar

Copy it somewhere on your PATH. The examples below just write fpsonar.

fpsonar --help

First analysis

edit

Point it at a file, a folder, or a Lazarus project:

fpsonar analyze myunit.pas
fpsonar analyze src/
fpsonar analyze myproject.lpi

The general form is:

fpsonar <command> [options] <target...>

A run that found something looks like this:

Fp-Sonar 0.1.0 - text report v1
myunit.pas:42:13: minor LowercaseKeywords: Keyword should be lowercase: write True
Analyzed 1 file(s): 1 issue(s).

Every issue line has the same shape:

myunit.pas : 42 : 13 : minor : LowercaseKeywords : Keyword should be lowercase
   file       line  col  severity   rule name          explanation

The rule name is the part to look up on the rule pages below when you want to know what a check means, or turn it off.

Severities and the quality gate

edit
Severity Meaning
blocker Almost certainly a real bug — fix it.
critical Very likely a problem.
major Worth fixing.
minor Small style or polish issue.
info Information; not a problem.

Severity is a hint about attention, not necessarily a potential bug — although a minor rule can still be pointing at a real bug.

A whole run also gets a pass/fail result, the so-called quality gate, reported through the exit code of the application:

Exit code Meaning
0 Passed.
1 The gate failed (too many serious issues).
2 Something was wrong with the command itself.

By default the gate fails only on blocker or critical issues. That makes fpSonar usable as a CI step directly: most CI systems fail a build when a step exits non-zero.

Analyzing a real project

edit

Real code depends on compiler settings to make sense. If a plain analyze produces a lot of "cannot find unit" noise, give fpSonar the settings your compiler uses:

fpsonar analyze src/ \
  -Mobjfpc \
  -dDEBUG \
  -Fu/path/to/other/units \
  -Fi/path/to/include/files
Option Meaning
-M<mode> Compiler mode, e.g. objfpc or delphi. Also --mode.
-d<NAME> Define a symbol, once per symbol. Also --define.
-Fu<path> Folder to find uses units in.
-Fi<path> Folder to find {$I} include files in.

Easiest of all: if you have a Lazarus .lpi, analyze that and these settings are taken from the project automatically.

Which symbols are defined matters to more than unit resolution — two rules on fpsonar_conditional_compilation answer questions about the define set, and give wrong answers when it is wrong.

Turning rules on and off

edit

Rules are configured in a JSON file passed with --config:

{
  "rules": {
    "LowercaseKeywords": { "enabled": false },
    "ConstantNaming":    { "params": { "pattern": "^c?[A-Z][A-Za-z0-9_]*$" } }
  },
  "gate": {
    "maxBlocker":  0,
    "maxCritical": 0,
    "maxMajor":   10
  }
}
fpsonar analyze src/ --config myrules.json

Rather than writing that from scratch, let fpSonar emit one listing every rule at its default state, with a params block for every tunable rule:

fpsonar init-config -o myrules.json

Many rules ship off by default — because they are new, or because they suit some projects and not others. Every rule page below says which. Turning one on is a deliberate choice.

Silencing findings

edit

For a single line, put a NOSONAR comment on it:

x := SomethingWeird();  // NOSONAR - intentional, see ticket #123

The marker is matched case-sensitively and must be upper case. // NoSonar and // nosonar silence nothing.

To silence in bulk — a whole rule, a whole folder, or a rule within a folder — use a suppressions list in the config file instead:

{
  "suppressions": [
    { "rule": "Naming*" },
    { "path": "*/legacy/*" },
    { "rule": "LineTooLong", "path": "*/generated/*.pas" }
  ]
}

A finding is silenced when both patterns match: its rule name matches rule and its path matches path. A field you leave out matches anything. The patterns are globs, matched case-sensitively.

Suppressing is not the same as disabling. A disabled rule does not run at all and cannot be scoped; a suppressed rule keeps running and only its matching findings are hidden — so you can keep a rule on everywhere except generated code or a legacy corner.

Existing large codebases

edit

You rarely want to fix thousands of old findings at once. Freeze today's issues by creating a baseline, then get notified only about new ones:

fpsonar baseline src/ --output baseline.json
fpsonar analyze src/ --new-code baseline.json

The gate then only considers problems introduced since the snapshot.

Output formats

edit
Format Use
text Human-readable; the default.
sarif Standard JSON many editors and code-review tools read.
sonar-json For feeding results into SonarQube.
fpsonar analyze src/ --format sarif --output report.sarif

Rule reference

edit

Each page explains its rules in plain language, with one example fpSonar accepts and one it complains about.

Every rule fpSonar has is documented on one of these pages.

Page Covers
fpsonar_naming What to call classes, records, fields, variables, units
fpsonar_layout Indentation, line length, tabs, trailing spaces
fpsonar_comments Comments, documentation, commented-out code
fpsonar_units_and_imports uses clauses, unit files, dotted units
fpsonar_declarations How to declare types, constants, variables, parameters
fpsonar_expressions Constants, ranges, casts, arithmetic that cannot work
fpsonar_control_flow if, case, loops, Exit, unreachable code
fpsonar_dataflow Variables read before they are set, values nothing reads
fpsonar_classes Classes, interfaces, properties, constructors
fpsonar_generics_and_closures Generic templates, anonymous methods, attributes
fpsonar_exceptions try, except, finally, raise
fpsonar_memory Create/Free, ownership, leaks
fpsonar_concurrency Threads, threadvar, touching the UI
fpsonar_strings String types, PChar, encodings
fpsonar_calls Calling RTL routines correctly
fpsonar_conditional_compilation {$ifdef} branches, guard symbols
fpsonar_portability Separators, line endings, record layout, byte counts
fpsonar_unused_code Declarations nothing uses
fpsonar_metrics Routines and units that have grown too large
fpsonar_fpc_conventions Conventions specific to the FPC source tree

Run fpsonar init-config to list every rule as it stands in your build, with its default enabled state, severity and parameters.

See also

edit