← Back to fpsonar
Eight rules that encode conventions of the Free Pascal source tree itself rather than of Object Pascal generally. They are worth more on this tree than any general-purpose rule, because nothing else checks them and violations are currently found by hand.
All are off by default. If you are not working inside the FPC tree, most of them will not apply to you.
Dotted units
editFPC ships each unit twice: under its historical short name (fpjson) and under a
namespaced dotted name (FpJson.Data). The dotted file is a three-line wrapper that
includes the original, and which name you get is decided by the FPC_DOTTEDUNITS
define. A unit that supports both therefore carries a guarded uses clause with two
branches.
The mapping between the two names is not derivable from the names themselves —
fpjson becomes FpJson.Data, pscanner becomes Pascal.Scanner. It is recorded in
a namespaces.lst file in each package, and fpsonar consults a consolidated table
built from all of them.
DottedUnitsBranchesInconsistent
editmajor · off by default
The two branches of an FPC_DOTTEDUNITS guard must list corresponding units. A unit
added to one branch and not the other builds in one configuration and fails in the
other — a recurring, mechanically avoidable breakage.
fpsonar complains about this
{$IFDEF FPC_DOTTEDUNITS}
uses
System.Classes, System.SysUtils, FpJson.Data;
{$ELSE}
uses
Classes, SysUtils; // fpjson missing from this branch
{$ENDIF}
fpsonar accepts this
{$IFDEF FPC_DOTTEDUNITS}
uses
System.Classes, System.SysUtils, FpJson.Data;
{$ELSE}
uses
Classes, SysUtils, fpjson;
{$ENDIF}
DottedUnitAliasMismatch
editmajor · off by default
Both branches list the same number of units, but a dotted name is not the recorded alias of its non-dotted counterpart — so the two branches import different units.
The rule resolves each pair through the mapping table built from namespaces.lst. If
a unit has no entry — a package without a namespaces.lst, or a unit added since the
table was generated — the rule stays silent rather than guessing. An unknown
mapping is not a mismatch.
fpsonar complains about this
{$IFDEF FPC_DOTTEDUNITS}
uses FpJson.Parser;
{$ELSE}
uses fpjson; // fpjson's alias is FpJson.Data, not FpJson.Parser
{$ENDIF}
fpsonar accepts this
{$IFDEF FPC_DOTTEDUNITS}
uses FpJson.Data;
{$ELSE}
uses fpjson;
{$ENDIF}
The table ships compiled into the binary, so this works with no setup. To check
against a newer table, regenerate it and pass --namespace-map <file>.
MissingDottedUnitsGuard
editminor · off by default
A uses clause in a file with no FPC_DOTTEDUNITS guard at all. New units in the
tree are expected to support both worlds.
fpsonar complains about this
unit Report;
interface
uses
Classes, SysUtils;
fpsonar accepts this
unit Report;
interface
{$IFDEF FPC_DOTTEDUNITS}
uses
System.Classes, System.SysUtils;
{$ELSE}
uses
Classes, SysUtils;
{$ENDIF}
Hint modifiers
editPascal lets a declaration carry deprecated, platform or experimental. The
compiler warns at use sites — unless hints are switched off, which is common in large
builds. These three rules report the uses independently, so the information survives.
DeprecatedSymbolUsed
editminor · off by default
A use of something declared deprecated. The declaration's message, if it has one, is
included in the report — that message usually names the replacement.
fpsonar complains about this
// declared elsewhere as: procedure OldLoad; deprecated 'use Load instead';
OldLoad;
fpsonar accepts this
Load;
ExperimentalSymbolUsed
editminor · off by default
A use of something declared experimental — an interface that may change without
notice. Worth knowing about before it changes.
fpsonar complains about this
// declared elsewhere as: procedure NewParse; experimental;
NewParse;
fpsonar accepts this
Parse;
PlatformSymbolUsedInPortableUnit
editminor · off by default
A platform-marked symbol used from a unit that is not itself marked platform. That
combination is how a portable unit quietly acquires a platform dependency — it compiles
on the developer's machine and fails on another target.
fpsonar complains about this
unit Report; // not marked platform
// WinSpecific is declared: procedure WinSpecific; platform;
begin
WinSpecific;
end;
fpsonar accepts this
{$IFDEF WINDOWS}
WinSpecific;
{$ELSE}
PortableEquivalent;
{$ENDIF}
Files
editMissingCopyrightHeader
editinfo · off by default
Every file in the FPC tree carries a leading comment referencing COPYING.FPC. This
rule reports files without one.
Expect a large number of findings the first time you enable it on an unfamiliar tree — this is a rule to run once, fix in bulk, and then keep on.
fpsonar complains about this
unit Report;
interface
fpsonar accepts this
{
This file is part of the Free Component Library (FCL)
Copyright (c) 2026 by the Free Pascal development team
See the file COPYING.FPC, included in this distribution,
for details about the copyright.
}
unit Report;
interface
LfmFormFileExists
editminor · on by default
A unit that declares a form, frame or datamodule but has no sibling .lfm file. The
.lfm holds the designed layout, so a missing one means the form loads empty at run
time — and the usual cause is a file that was never added to version control.
fpsonar complains about this
// report.pp declares TReportForm, but there is no report.lfm beside it
type
TReportForm = class(TForm)
end;
fpsonar accepts this
// report.pp and report.lfm both present
Related chapters
editUnitFileNameCaseMismatch and MissingModeDirective are also FPC conventions, but
they concern the uses clause and the unit file, so they live in
units and imports. The documentation-comment convention is
in comments.
See also
edit- fpsonar — what fpSonar is, and how to run it
← Back to fpsonar