Fpsonar fpc conventions

← 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

edit

FPC 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

edit

major · 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

edit

major · 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

edit

minor · 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

edit

Pascal 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

edit

minor · 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

edit

minor · 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

edit

minor · 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

edit

MissingCopyrightHeader

edit

info · 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

edit

minor · 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
edit

UnitFileNameCaseMismatch 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