.PAS File Format – Units and libraries

Pascal source code

The uses clause

program Demo;
uses
  SysUtils, Classes,                  { units on the search path }
  Strings in 'lib\Strings.pas',       { a unit at a given file (Delphi) }
  Winapi.Windows;                     { a unit with a scope prefix }

uses lists the units whose interface a program or unit wants to see. The compiler finds each unit as a compiled file (.dcu, .ppu, .tpu) or as source (.pas, .pp) on its search paths; Free Pascal uses -Fu options, {$UNITPATH} and fpc.cfg, Delphi the project’s search path. The in 'file' form names the source file.

  • A unit that is used makes its interface names visible. When two units declare the same name, the unit that comes later in the uses list wins, and Unit.Name picks one.
  • System (and in Delphi and Free Pascal modes ObjPas) is always used and need not be listed.
  • Circular use: unit A may use unit B in its implementation part while B uses A in its interface part. Both in the interface is an error.
  • A unit compiled before is recompiled when its source or one of the units it uses has changed.

Initialisation order

Before the main block runs, the initialization part of every unit runs, in an order such that a unit initialises after the units its interface uses (and the units in a uses clause are taken left to right otherwise). When the program ends, the finalization parts run in the reverse order. In Turbo Pascal the begin-end block at the end of a unit is the initialisation. Libraries (DLLs) run them when loaded and unloaded.

Libraries and external routines

{ calling a routine in a DLL }
function MessageBoxA(Wnd: HWND; Text, Caption: PAnsiChar; Flags: UINT): Integer;
  stdcall; external 'user32.dll' name 'MessageBoxA';

{ by ordinal }
function GetThing: Integer; stdcall; external 'thing.dll' index 3;

{ a C library in Free Pascal }
function strlen(S: PChar): SizeInt; cdecl; external 'c' name 'strlen';

{ delay-load }
procedure Optional; external 'opt.dll' name 'Optional' delayed;

A routine with the external directive has no body: its code is in a DLL, a shared library or a linked object file, found by the name, with name or index to choose the exported entry. The calling convention must be the one the library uses (stdcall for the Windows API, cdecl for C). Free Pascal also links objects with {$L file.o} and libraries with {$LINKLIB name}. To make a library, write a library and list the exported routines in exports (see File structure). A library may also be loaded by hand with LoadLibrary and GetProcAddress (Windows) or dlopen and dlsym (Unix) into a variable of a procedural type; Free Pascal’s dynlibs unit has LoadLibrary, GetProcedureAddress and UnloadLibrary for both.

Packages

  • A Delphi package (.dpk source, .bpl binary) is a set of units that can be loaded by a program or by the IDE at run time. The requires list names the packages it needs and contains the units it holds. {$DESIGNONLY} and {$RUNONLY} mark a package for the IDE or for run time only, and {$DENYPACKAGEUNIT} keeps a unit out of packages.
  • A Lazarus package (.lpk, XML) lists units and dependencies for Lazarus and its package manager, and Free Pascal’s own packages are described with fpmake.pp and built with the fpmake tool. Both are not Pascal source, though fpmake.pp is.
  • A unit scope is a prefix in a dotted unit name (Vcl.Forms), and a project may list default scopes to search (Delphi).

Include files and macros

{$I name.inc} pastes another file at that point. It is used to share constants between programs, to select code for a platform ({$I platform.inc}) and to split a big unit. {$I %FILE%} and the other compiler information includes insert strings, and Free Pascal macros ({$MACRO ON}{$DEFINE NAME := text}) replace names with text. {$INCLUDEPATH} adds where includes are looked for.

Resources

  • {$R file.res} links a compiled Windows resource file (icons, version information, forms, dialogs, strings); {$R *.res} uses the program’s name, {$R *.dfm} a unit’s form file. Lazarus can also keep a form as an .lrs include file read with {$I unit1.lrs}.
  • resourcestring declares strings that are put in the resource table so that they can be replaced without recompiling.
  • Resources are read at run time with FindResource, LoadResource and TResourceStream (Delphi and Free Pascal).

Conditional compilation

A program that should build on several compilers and systems uses {$IFDEF …} branches around the parts that differ; symbols such as FPC, MSWINDOWS, UNIX, CPU64 and VERnnn tell which compiler and system it is. The directives and the predefined symbols are on Compiler directives.

{$IFDEF FPC}
  {$mode delphi}
{$ENDIF}
unit Portable;
interface
{$IFDEF MSWINDOWS}
const PathSep = '\';
{$ELSE}
const PathSep = '/';
{$ENDIF}