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
editfpSonar 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
editPoint 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
editReal 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
editRules 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
editFor 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
editYou 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
editEach 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.