Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 36 ยท Units and Object Pascal

Units and the uses Clause

Split a Pascal or Delphi program into units, learn how the uses clause finds code, how name clashes are resolved, and how compiled units are built and linked.

A small Pascal program fits in a single file. A real one does not. Once you have a few hundred lines, you want to group related code (math helpers, a customer record, a logger) into separate files that you can reuse and test on their own. In Pascal, that building block is the unit.

A unit is a source file with a name, a public part that other code may see, and a private part that only the unit itself can use. A program or another unit pulls a unit in with a uses clause. This lesson covers the shape of a unit, how uses works, what happens when two units define the same name, and how the compiler turns units into a finished program.

Delphi and Free Pascal/Lazarus are the two main compilers for Object Pascal. This site cannot run either of them, so the Pascal code in this chapter is shown read-only. Each lesson also has a runnable C program that models the same idea (marked "stand-in"), so you can watch the mechanism work. Where output is shown for Pascal, it is output we are certain about.

The anatomy of a unit

Every unit has the same skeleton. Save this as MathUtils.pas:

PASCAL
unit MathUtils;

interface

function Square(X: Integer): Integer;
function Clamp(Value, Low, High: Integer): Integer;

implementation

function Square(X: Integer): Integer;
begin
  Result := X * X;
end;

function Clamp(Value, Low, High: Integer): Integer;
begin
  if Value < Low then
    Result := Low
  else if Value > High then
    Result := High
  else
    Result := Value;
end;

end.

The unit name on the first line must match the file name. The interface section lists what the unit offers: only the headings of routines, plus types, constants and variables. The implementation section holds the bodies. The final end. (with a period) closes the unit, just as it closes a program. The next lesson looks closely at the split between the two sections.

Using a unit

A program lists the units it needs after uses:

PASCAL
program Demo;

uses
  MathUtils;

begin
  WriteLn(Square(7));         // 49
  WriteLn(Clamp(120, 0, 100)); // 100
end.

The compiler looks for MathUtils in the current project, then in the search paths you configured. Names from the interface section become visible in the program, exactly as if they had been declared there. Anything declared only in the implementation section stays hidden.

In Delphi, standard units live in unit scopes such as System, Vcl, FMX and Data. You write uses System.SysUtils, System.Classes;. Free Pascal uses older flat names like SysUtils and Classes. Delphi can also resolve the short forms if you add the scope to the project's "unit scope names" option.

Name clashes: the last unit wins

Two units may declare the same identifier, for example both define a function Max. If a program names both in uses, the one listed last wins when you write the bare name:

PASCAL
uses
  UnitA, UnitB;   // both define Max; UnitB.Max is the one you get

begin
  WriteLn(Max(3, 9));          // UnitB.Max
  WriteLn(UnitA.Max(3, 9));    // qualified: always UnitA's
end.

You can always write UnitName.Identifier to be explicit. That is the cleanest fix for a clash, and the reason many teams prefer qualified names for anything ambiguous. Reordering uses to "fix" a clash is fragile: it changes meaning silently.

The stand-in below simulates this lookup. Each unit registers a name, and resolving a bare name searches from the last unit back to the first, while a qualified name goes straight to one unit.

C Stand-in: how 'last unit wins' resolves a name

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Swap the first two rows of scope and run again: the bare Max now resolves to a different function. That is the same silent change you would get by reordering a uses clause.

From source to program

Compiling a Pascal program is quick because every unit is compiled once into a binary form and reused:

From unit to program

Source MathUtils.pas
Compile Each unit once
Compiled unit .dcu or .ppu
Link One executable

Unchanged units are not recompiled

1 / 2

Delphi writes .dcu files and Free Pascal writes .ppu plus an object file. When you change MathUtils.pas, the compiler rebuilds it and every unit that depends on its interface. If you only change a function body in the implementation section, units that use it need no rebuild. This is one reason Pascal builds are famously fast.

Programs, units and libraries

A program file is the entry point: it has a begin ... end. main block. A unit has no main block (though it can have initialization code, see initialization and finalization). A library produces a DLL or shared object. In Delphi projects, the .dpr file is the program file and mostly lists the other units, and the IDE manages it for you.

Common mistakes

  • Unit name does not match file name. unit MathUtil; saved as MathUtils.pas gives "file not found" errors in other units.
  • Forgetting to add a unit to uses. You get "Undeclared identifier".
  • Putting everything in interface. Expose only what callers need.
  • Relying on uses order to resolve clashes instead of qualifying the name.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which section of a unit contains the bodies of its routines?

    The interface lists headings only. The bodies, and anything private, live in the implementation section.
  2. 2. UnitA and UnitB both declare Max. A program has uses UnitA, UnitB; and calls Max(1, 2). Which one runs?

    The unit listed last in the uses clause wins for a bare name. Write UnitA.Max to be explicit.
  3. 3. What does a unit's end. with a period do?

    The final end. terminates the unit, just as it terminates a program. Without it the compiler reports an error.
  4. 4. Why are Pascal builds fast?

    Compiled units (.dcu or .ppu) are reused, and only changed units and their dependents are rebuilt.

Summary

  • A unit has a name, an interface (public) and an implementation (private) section, and ends with end..
  • Programs and units import other units with uses.
  • With a name clash, the unit listed last wins; qualify names with UnitName.Identifier to be explicit.
  • Units are compiled once and reused, so builds are quick.
  • Delphi uses dotted unit scopes (System.SysUtils); Free Pascal uses flat names (SysUtils).

Next: Interface and Implementation Sections