Toolchain on TurboVision

Turbo Pascal Toolchain, Part 6: Object Pascal, TPW, and the Windows Transition

Fri, 13 Mar 2026 00:00:00 +0000

Parts 1–5 mapped the DOS-era toolchain: workflow, artifacts, overlays, BGI, and the compiler/linker boundary from TP6 to TP7. This part crosses the platform divide. Object Pascal extensions, Turbo Pascal for Windows (TPW), and the move to message-driven GUIs forced a different kind of toolchain thinking. Same language family, new mental model.

This article traces that transition from a practitioner’s perspective: what stayed familiar, what broke, and what had to be relearned. We cover the historical milestones (TP 5.5 OOP, TPW 1.0, TPW 1.5, BP7), the technical culprits that bit migrating teams, debugging and build/deploy workflow differences, and the mental shift from sequential to event-driven execution.

Version timeline (conservative): TP 5.5 (1989) introduced Object Pascal. TPW 1.0 appeared in the Windows 3.0 era (c. 1991). Borland Pascal 7 (1992) offered unified DOS and Windows tooling including DLL support. TPW 1.5 followed TP7 (c. 1993). OWL matured alongside these releases. Exact dates for some variants vary by region and packaging; the sequence is well established. The transition spanned roughly four years; many teams maintained both DOS and Windows targets during that period.

Structure map (balanced chapter plan)

Before drilling into details, this article follows a fixed ten-chapter plan so the narrative stays balanced rather than front-loaded:

Object Pascal in TP 5.5
TPW 1.0 and first Windows workflow shock
TPW 1.5 in the post-TP7 landscape
BP7 as dual-target toolchain
OWL and message-driven architecture
migration culprits and pitfalls
debugging model changes (DOS vs Windows)
build/deploy pipeline changes
team workflow and review-model changes
synthesis and transfer lessons

Each chapter carries similar depth: technical mechanism, failure mode, and practical operator/developer workflow.

Object Pascal arrives: TP 5.5 and the OOP extensions

Turbo Pascal 5.5, released in 1989, introduced Object Pascal: the object type with inheritance, virtual methods, and constructors/destructors. The additions were substantial for the language, but the toolchain remained essentially the same. Compile, link, run. .TPU units still carried compiled code; the linker still produced .EXE. What changed was what you expressed in those units and how you structured larger programs.

The object keyword (distinct from the later class keyword in Delphi) defined a type with a hidden pointer to its virtual method table (VMT). Inheritance was single; you could not inherit from multiple base objects. Virtual methods required the virtual directive and had to be overridden with the same signature. The compiler emitted the VMT layout; if you got the inheritance hierarchy wrong, the wrong method could be invoked at runtime—a form of bug that procedural Pascal had never had.

unit Shapes;

interface

type
  TShape = object
    X, Y: Integer;
    procedure Move(Dx, Dy: Integer);
    procedure Draw; virtual;
    constructor Init(AX, AY: Integer);
    destructor Done; virtual;
  end;

  TCircle = object(TShape)
    Radius: Integer;
    procedure Draw; virtual;
    constructor Init(AX, AY, ARadius: Integer);
  end;

implementation

constructor TShape.Init(AX, AY: Integer);
begin
  X := AX;
  Y := AY;
end;

destructor TShape.Done;
begin
  { cleanup }
end;

procedure TShape.Move(Dx, Dy: Integer);
begin
  Inc(X, Dx);
  Inc(Y, Dy);
end;

procedure TShape.Draw;
begin
  { base: no-op or default behavior }
end;

constructor TCircle.Init(AX, AY, ARadius: Integer);
begin
  TShape.Init(AX, AY);
  Radius := ARadius;
end;

procedure TCircle.Draw;
begin
  { draw circle at X,Y with Radius }
end;

end.

For DOS projects, this was still a single-threaded, linear-control-flow world. The object model improved structure and reuse; it did not yet change the execution paradigm. Overlays, BGI, and conventional memory limits applied unchanged. Teams adopting Object Pascal in the late 1980s learned inheritance and polymorphism while keeping familiar toolchain habits.

Constructor and destructor discipline mattered. In the early object model (pre-class syntax), you called Init explicitly and Done before disposal. Forgetting Done on objects that held resources (handles, memory) leaked. The toolchain did not enforce this; it was a coding discipline. Virtual method tables added a small runtime cost and one more thing to get wrong when mixing object types—passing a TShape where a TCircle was expected could produce subtle bugs if the receiver assumed the concrete type.

The important point for the Windows transition: Object Pascal gave developers the vocabulary (inheritance, virtual dispatch, encapsulation) that OWL and later frameworks would use. Learning OOP in DOS was preparation for OWL’s message-handler hierarchy.

Toolchain impact was minimal. TP 5.5 still produced .TPU units; the compiler emitted VMT layout for object types; the linker resolved virtual calls at link time. Debugging object hierarchies required understanding the VMT structure, but Turbo Debugger could display object instances and their fields. Migration from procedural to object-based code was incremental: one unit at a time, starting with leaf modules that had no dependencies. A common path: introduce a single object type to encapsulate a record and its operations, compile and test, then add inheritance where it simplified structure. Big-bang rewrites to “full OOP” were rare and risky; most teams evolved their codebases gradually.

Turbo Pascal for Windows 1.0: the first wave

Turbo Pascal for Windows 1.0 arrived in the Windows 3.0 era, commonly cited as around 1991. The toolchain surface looked familiar: blue IDE, integrated compiler, linker. Underneath, the target was completely different. Instead of DOS .EXE and real-mode segments, you produced Windows .EXE binaries that linked against the Windows API, expected a GUI entry point (WinMain), and ran inside a message loop.

First-time TPW users discovered that a “Pascal program” was no longer a straight-line script. The main block ran once to register the window class, create the main window, and enter GetMessage/DispatchMessage. After that, everything happened inside the window procedure (WndProc) in response to messages. A typical beginner error: putting “real” logic in the main block, wondering why it never ran, and only later realizing the block had already exited into the message loop. Another: assuming that WndProc would be called once per “event.” In fact, Windows sends many messages—WM_CREATE, WM_SIZE, WM_PAINT, WM_COMMAND, and dozens more—and the order and timing depend on user actions and system behaviour. Learning which messages mattered for a given task was part of the ramp-up.

program HelloWin;

uses
  WinTypes, WinProcs;

const
  IDC_BUTTON = 100;

function WndProc(Window: HWnd; Message, WParam: Word; LParam: LongInt): LongInt;
  far;
begin
  case Message of
    wm_Command:
      if WParam = IDC_BUTTON then
        MessageBox(Window, 'Hello from TPW', 'TPW', mb_Ok);
    wm_Destroy:
      PostQuitMessage(0);
    else
      WndProc := DefWindowProc(Window, Message, WParam, LParam);
      Exit;
  end;
  WndProc := 0;
end;

var
  Msg: TMsg;
  WndClass: TWndClass;
  hWnd: HWnd;

begin
  WndClass.style := 0;
  WndClass.lpfnWndProc := @WndProc;
  WndClass.cbClsExtra := 0;
  WndClass.cbWndExtra := 0;
  WndClass.hInstance := HInstance;
  WndClass.hIcon := LoadIcon(0, idi_Application);
  WndClass.hCursor := LoadCursor(0, idc_Arrow);
  WndClass.hbrBackground := GetStockObject(white_Brush);
  WndClass.lpszMenuName := nil;
  WndClass.lpszClassName := 'HelloWin';

  RegisterClass(WndClass);
  hWnd := CreateWindow('HelloWin', 'TPW Hello', ws_OverlappedWindow,
    cw_UseDefault, 0, cw_UseDefault, 0, 0, 0, HInstance, nil);
  ShowWindow(hWnd, sw_ShowNormal);
  UpdateWindow(hWnd);

  while GetMessage(Msg, 0, 0, 0) do
  begin
    TranslateMessage(Msg);
    DispatchMessage(Msg);
  end;
end.

The shift was conceptual: instead of “run from top to bottom,” you “register a window class, create a window, then sit in a message loop.” Event handling was reactive. The toolchain still produced .EXE, but the runtime contract was Windows API calls, far procs, and GetMessage/DispatchMessage.

TPW 1.0 shipped with WinTypes and WinProcs units (API bindings) and optionally WinCrt for console-style apps. The IDE looked like the DOS Turbo Pascal IDE but targeted a different runtime. Keyboard shortcuts and menu structure were familiar, which eased the transition. The debugger, however, had to handle a different execution model: breakpoints in message handlers fired when messages arrived, not when you single-stepped through a linear flow. Setting a breakpoint in WndProc and running would eventually stop there—but only when a message was dispatched to that window. First-time TPW users often hit: wrong library linking (mixing DOS and Windows units), missing far on WndProc, and confusion about when their code actually ran—the main block sets up and enters the loop; the rest happens inside WndProc when messages arrive. That inversion was the core mental break.

Linker differences mattered. TPW produced Windows executables with a different header format, different segment layout, and different startup code. You could not link a DOS object file into a Windows executable or vice versa. Mixed projects—e.g. a shared algorithm library—had to compile the same source twice, once for each target, with target-specific uses and possibly {$IFDEF} guards. The idea of “one binary runs everywhere” did not exist; you had DOS binaries and Windows binaries.

Understanding the message loop was essential. GetMessage blocks until a message is available; TranslateMessage converts keystrokes to WM_CHAR when needed; DispatchMessage invokes the window procedure for the target window. Every GUI action in a Windows app flows through this pipeline. A handler that did too much work (e.g. a long computation) would block the loop and freeze the UI. DOS programs could ReadKey and wait indefinitely; Windows programs had to return from handlers quickly and defer heavy work (e.g. via timers or background processing) to avoid stalling the whole application. Developers coming from DOS often wrote handlers that performed synchronous file I/O or lengthy calculations, then wondered why the window would not repaint or respond to input until the operation finished. The fix was to break work into smaller chunks or use PeekMessage-based cooperative multitasking—a technique that required unlearning the “run until done” habit.

TPW 1.5 and the post-TP7 landscape

TPW 1.5 followed TP7 and appeared in the early 1990s (often cited around 1993). It brought the TP7-era language and tooling to the Windows target. Better integration with Windows APIs, improved resource tooling, and alignment with the Borland Pascal 7 family. By this point, DOS and Windows were parallel targets within the same product family, not separate products with different pedigrees.

Build workflows diversified. A team might maintain both a DOS and a Windows configuration: different compiler switches, different libraries, different entry points. Shared units had to stay abstract enough to compile for both.

{ Conditional compilation for dual-target units }
unit SharedCore;

interface

procedure DoWork(Data: Pointer);

implementation

{$IFDEF MSWINDOWS}
uses WinTypes, WinProcs;
{$ENDIF}
{$IFDEF MSDOS}
uses Dos;
{$ENDIF}

procedure DoWork(Data: Pointer);
begin
  {$IFDEF MSWINDOWS}
  { Windows-specific implementation }
  {$ENDIF}
  {$IFDEF MSDOS}
  { DOS-specific implementation }
  {$ENDIF}
end;

end.

The {$IFDEF} pattern became standard for code shared across targets. Not all logic could be shared; APIs differed. But data structures, algorithms, and business rules could live in common units with thin platform-specific wrappers. Teams learned to minimize {$IFDEF} surface and push platform branches to dedicated units.

A common layout: a Core unit with pure logic (no uses of platform units), a CoreDOS unit that implemented Core for DOS (overlays, BGI, Dos unit), and a CoreWin unit that implemented Core for Windows (handles, WinProcs). The program or a top-level unit chose which implementation to use. This kept the conditional compilation at a few strategic points rather than scattered throughout.

TPW 1.5 also improved the resource workflow. Earlier TPW had resource support, but the integration was rougher. By 1.5, the path from dialog design to linked .EXE was more streamlined, and teams doing serious Windows development could rely on it.

A practical consideration: machine requirements. DOS Turbo Pascal ran on an 8088 with 256 KB of RAM. TPW and Windows 3.x demanded more—typically a 286 or 386, 1 MB or more of RAM, and a graphics display. Teams developing on higher-end machines had to remember that target users might have minimal configurations. Testing on a “cramped” setup (e.g. 1 MB RAM, 640×480) caught memory pressure and layout bugs that did not appear on development hardware.

BP7: unified DOS and Windows toolchain

Borland Pascal 7, released in 1992, provided a single box with DOS and Windows support. You could build:

DOS executables (with overlays, EMS, real-mode semantics)
Windows executables
Windows DLLs

DLL building introduced a new artifact type and a new linkage model.

library MyLib;

uses
  WinTypes, WinProcs;

exports
  MyExportProc index 1,
  MyExportFunc index 2;

procedure MyExportProc(P: PChar); far;
begin
  { DLL-exported procedure }
end;

function MyExportFunc(I: Integer): Integer; far;
begin
  MyExportFunc := I * 2;
end;

begin
  { DLL entry/exit handling if needed }
end.

The toolchain produced .DLL instead of (or in addition to) .EXE. Callers used LoadLibrary and GetProcAddress. Version coupling and calling conventions mattered more: a Pascal DLL had to match what the caller expected. Teams learned to isolate DLL interfaces and treat them as stable ABI boundaries.

DLL entry and exit ran at load/unload. If a DLL’s initialization touched other DLLs or global state, load order could cause subtle failures. Export by name vs. by ordinal had tradeoffs: ordinals were smaller and faster to resolve but fragile if the export table changed. Many teams standardized on name-based exports for maintainability and reserved ordinals for performance-critical paths. The exports section in the library block was the contract; changing it broke any caller that relied on it. Adding new exports was usually safe; removing or reordering required coordinated updates to all clients. Teams that treated the DLL interface as a stable API and versioned it explicitly (including in documentation) had fewer integration surprises.

Calling a Pascal DLL from C or another language required matching conventions: pascal vs. cdecl, near vs. far, and structure layout. Teams building mixed- language systems documented the ABI explicitly. A small test program that called each exported function and verified return values caught many integration bugs before they reached production.

BP7’s value was consolidation: one purchase, one documentation set, one support channel for both DOS and Windows. Teams could prototype on DOS (faster iteration, simpler debugging) and port to Windows when the design stabilised, or maintain both targets from a shared codebase from the start.

The DLL workflow itself took time to internalise. A library program had no main loop; it exported entry points. Callers loaded it, resolved exports, and called. The DLL’s initialization block ran at load; its finalization (if any) ran at unload. Thread safety was not a primary concern in 16-bit Windows, but DLL global state was shared across all callers. A bug in one executable’s use of a DLL could corrupt state for another. Documentation and code review had to cover “who loads this DLL, when, and what do they assume about its state?” DLLs also changed the testing matrix: a fix in a shared DLL required re-testing every application that used it. Versioning the DLL (e.g. embedding a version resource) and checking it at load time caught many “wrong DLL” deployment bugs before they manifested as mysterious crashes.

Importing a DLL from Pascal required matching the export signature exactly. A common pattern:

{ In unit that uses the DLL }
procedure MyImportProc(P: PChar); far; external 'MYLIB' index 1;
function MyImportFunc(I: Integer): Integer; far; external 'MYLIB' index 2;

If the DLL used pascal convention (Borland default) and the caller did too, calls worked. Mixing cdecl and pascal caused stack corruption. Teams building reusable DLLs often documented the calling convention in the header or in a separate ABI document.

OWL and message-driven architecture

Object Windows Library (OWL) and similar frameworks wrapped the raw Windows API in an object-oriented, message-handler style. Instead of a giant case statement in a single WndProc, you subclassed window types and overrode message handlers.

unit MyWindow;

interface

uses
  Objects, WinTypes, WinProcs, OWindows;

type
  PMyWindow = ^TMyWindow;
  TMyWindow = object(TWindow)
    procedure WMCommand(var Msg: TMessage); virtual wm_First + wm_Command;
    procedure WMPaint(var Msg: TMessage); virtual wm_First + wm_Paint;
  end;

implementation

procedure TMyWindow.WMCommand(var Msg: TMessage);
begin
  if Msg.WParam = 100 then
    MessageBox(HWindow, 'Button clicked', 'OWL', mb_Ok)
  else
    inherited WMCommand(Msg);
end;

procedure TMyWindow.WMPaint(var Msg: TMessage);
var
  PS: TPaintStruct;
  DC: HDC;
begin
  DC := BeginPaint(HWindow, PS);
  { draw using DC }
  EndPaint(HWindow, PS);
end;

end.

The pattern: each message maps to a virtual method; inherited propagates to the default handler. Toolchain-wise, you still compiled units and linked, but the design idiom was “object per window, method per message.” This influenced how teams structured code and how they debugged: failures showed up as wrong message routing or missing overrides.

OWL abstracted the raw RegisterClass/CreateWindow/message-loop boilerplate. You derived from TApplication and TWindow, filled in handlers, and the framework dealt with registration and dispatch. The tradeoff: learning OWL’s object graph and lifecycle. Windows created by OWL were owned by the framework; manual CreateWindow calls mixed with OWL could bypass that ownership and cause duplicate destruction or leaked handles. Teams that went “all OWL” had fewer ownership bugs than those that mixed raw API and OWL freely.

The virtual wm_First + wm_Command syntax mapped a Windows message ID to a method. When a message arrived, OWL’s dispatch logic looked up the method and called it. If you did not override a message, the base class handled it (or passed to DefWindowProc). This was a clean separation of concerns: each window class handled only the messages it cared about.

{ OWL: creating a custom control by inheritance }
type
  PMyEdit = ^TMyEdit;
  TMyEdit = object(TEdit)
    procedure WMChar(var Msg: TMessage); virtual wm_First + wm_Char;
  end;

procedure TMyEdit.WMChar(var Msg: TMessage);
begin
  { Filter or transform input before default handling }
  inherited WMChar(Msg);
end;

This pattern—override, do something, call inherited—became the standard for extending OWL controls. The toolchain compiled and linked the same way; the design vocabulary had expanded.

Choosing between raw API and OWL was a real decision. Raw API gave full control and smaller binaries but required more boilerplate and discipline. OWL added framework overhead but let teams ship Windows apps faster. Many TPW projects started with raw API for learning, then switched to OWL once the team understood the message model. Hybrid approaches existed but demanded careful ownership rules for window handles and resources.

OWL also provided standard dialogs, common controls wrappers, and application lifecycle management. Reinventing these with raw API was possible but time- consuming. Teams that adopted OWL early often had a working prototype in days instead of weeks. The tradeoff was dependency on Borland’s framework and its design decisions; customising behaviour sometimes required diving into OWL source or working around framework limitations. For teams building multiple Windows applications, OWL’s consistency across projects was valuable: once you learned the patterns, new apps came together faster. The investment in learning the framework paid off over several products.

Technical culprits and pitfalls

Several failure modes were common when moving from DOS to Windows. Experienced DOS developers often hit these first; the habits that worked in real mode backfired in Windows.

Far-call discipline. Windows callback procs (WndProc, dialogs, hooks) must be far. The Windows kernel and USER module invoke your code through function pointers; in the segmented 16-bit model, a near call to a callback caused immediate corruption when the system tried to return. Missing far or wrong declaration led to crashes that were hard to reproduce—sometimes only when a particular code path was taken. The compiler did not always catch it; runtime did, and not always with a clear message.

Resource coupling. Windows apps depend on .RC resources (dialogs, menus, icons). Wrong paths, missing resources, or mismatched IDs produced obscure startup failures. The linker or resource compiler had to be in the loop, and the resulting .RES had to link into the .EXE. A dialog defined in .RC with control ID 100 had to match the wm_Command handler that checked for 100. Typos or reuse of IDs across dialogs caused wrong controls to be identified. Teams learned to centralize ID constants in a shared include or unit. Some teams used a naming scheme (e.g. IDC_BUTTON_SAVE, IDC_EDIT_NAME) to make the link between resource and handler obvious during code review.

Segment and memory model. Windows 3.x used segmented memory. Large allocations, wrong segment assumptions, or stack overflow in message handlers could corrupt the heap or cause intermittent faults. DOS habits (assume sequential execution, small stack) did not translate. In DOS, you often knew exactly when a procedure returned; in Windows, a message handler could call SendMessage and re-enter the same or another handler before returning. Recursive message handling required care with stack depth and static state.

String interop. Pascal String[N] vs. C null-terminated. Windows API expects PChar and length conventions. Conversion bugs caused truncation, buffer overrun, or wrong display. Teams needed explicit conversion layers and disciplined use of buffers.

DLL load order and initialization. DLLs had init/exit sequences. Circular dependencies or incorrect load order led to startup hangs or access violations. Build order and uses discipline mattered.

String conversion and buffer safety. Windows API calls often expect null-terminated PChar. Pascal String is length-prefixed. Passing a raw String variable where PChar was expected could work by accident (many implementations had a trailing zero) but was undefined. Correct pattern:

{ Safe Pascal-to-Windows string passing }
procedure ShowText(const S: String);
var
  Buf: array[0..255] of Char;
  I: Integer;
begin
  for I := 0 to Length(S) - 1 do
    Buf[I] := S[I + 1];  { Pascal 1-based indexing }
  Buf[Length(S)] := #0;
  MessageBox(0, Buf, 'Title', mb_Ok);
end;

Teams built small conversion units and used them consistently. Ad-hoc StrPCopy calls scattered across codebases were a maintenance hazard. A StrUtils or WinStrings unit with PascalToPChar, PCharToPascal, and perhaps PCharBuf for temporary buffers reduced copy-paste errors and gave a single place to fix bugs when a new Windows version changed length semantics.

{ Common mistake: forgetting far on Windows callbacks }
procedure BadProc(Window: HWnd; Msg: Word; W, L: LongInt);  { WRONG }
procedure GoodProc(Window: HWnd; Msg: Word; W, L: LongInt); far;  { CORRECT }

Debugging workflows: DOS vs Windows

DOS debugging was relatively direct. Single process, linear execution, predictable crash locations. Turbo Debugger could single-step, set breakpoints, inspect memory. Overlay and BGI issues were usually reproducible. If a crash happened at a fixed address, you set a breakpoint there, ran again, and examined the call stack. Deterministic replay was the default.

Windows debugging was harder. Message-driven execution meant control flow jumped between handlers. A bug might only appear when a specific message arrived in a specific order. Reproducing required driving the UI in a particular way. Crashes could occur in system code invoked via callback; the immediate cause might be bad parameters passed from your handler. Null pointer dereferences, wrong handle usage, and stack corruption in message handlers produced intermittent failures that did not correlate with “run it again.”

{ Diagnostic: log message flow to understand ordering }
procedure TMyWindow.DefaultHandler(var Msg: TMessage);
begin
  WriteLn(DebugFile, 'Msg=', Msg.Msg, ' W=', Msg.WParam, ' L=', Msg.LParam);
  inherited DefaultHandler(Msg);
end;

Practitioners used:

OutputDebugString and a monitor (e.g. Turbo Debugger for Windows or third-party tools) to capture log output
Conditional breakpoints in the debugger on message IDs (e.g. break when Msg.Msg = wm_Paint)
Small harness programs that sent specific messages via SendMessage to isolate behavior without manual UI interaction
Map files to correlate addresses with symbols when analyzing postmortem dumps

The mental shift: from “re-run until it crashes” to “instrument and trace message flow.” Debugging became hypothesis-driven: which message, which window, which order?

Another technique: build a minimal reproduction. If the bug appeared when clicking a specific button after resizing the window, create a tiny app with only that button and that resize logic. Isolating the failure often revealed that the cause was not where intuition suggested—e.g. a WM_PAINT handler that assumed state set up in WM_SIZE, but WM_PAINT could arrive before WM_SIZE in certain scenarios. Understanding Windows’ message ordering and reentrancy was as important as knowing the API. A handler that called SendMessage to a child window could find itself re-entered if the child’s handler did something that triggered another message to the parent. Careful design avoided such cycles; when they occurred, stack overflow or corrupted state often resulted.

Build and deploy: DOS vs Windows

DOS deployment was simple: .EXE, optionally .OVR, and .BGI/.CHR in a known directory. Batch files or simple install scripts sufficed. A typical release package: one folder, a few files, run the EXE. Path assumptions (e.g. .\BGI for drivers) had to be correct, but the surface was small. Floppy distribution was common: a single disk for the program, optionally a second for BGI drivers or overlay files. Users understood “copy to C:\MYAPP and run.”

Windows deployment added:

Multiple DLLs (Windows system DLLs plus any you shipped)
Resource files (icons, dialogs) embedded or alongside
INI files or registry for configuration
Different machine profiles (video drivers, memory)

The resource pipeline was new. You authored .RC files, compiled them with BRC.EXE (Borland Resource Compiler) to .RES, and linked the .RES into the .EXE. Forgetting the resource step produced a binary that ran but showed no icon, wrong menu, or broken dialogs. Dialog editor output and hand-written .RC had to stay in sync; ID collisions caused mysterious behavior. A small convention helped: define all resource IDs in a single $I-included file or a dedicated unit, and reference them from both .RC and Pascal. Changing an ID in one place without the other was a frequent source of “the button does nothing” bugs that took hours to track down.

REM DOS build
tpc -B main.pas
copy main.exe dist\
copy *.ovr dist\ 2>nul
copy bgi\*.bgi dist\bgi\

REM Windows build (conceptual)
tpw main.pas
brc main.res main.exe
copy main.exe dist\
copy mylib.dll dist\ 2>nul

Build scripts had to branch by target. Release builds often required separate configurations for DOS and Windows, with different linker options and runtime selection. Teams documented “DOS build checklist” vs. “Windows build checklist” and treated them as separate pipelines. A dual-target product meant two release builds, two test passes, and two support matrices (e.g. “runs on DOS 5.0+” vs. “runs on Windows 3.1+”).

Versioning of deliverables also changed. A DOS product might ship “v1.2”; a Windows product might need “v1.2 for Windows 3.1” vs. “v1.2 for Windows 3.11” if patch-level differences mattered. Installer design entered the picture: copying files into the right place, registering extensions, and creating program group icons. Teams that had never needed an “install” step had to learn one. Early Windows installers were often batch files or simple scripts; later, dedicated installer tools (e.g. Borland’s own offerings) became part of the release workflow. The transition from “copy to floppy and run” to “run setup and follow the wizard” was another incremental change that accumulated over the early 1990s.

Team collaboration and mental model shift

DOS-era teams had a shared mental model: one process, one flow, predictable artifacts. Code reviews focused on logic, overlays, and memory. A developer could read a program from top to bottom and follow execution. Ownership of “the main loop” was clear.

Windows-era teams dealt with:

Split expertise: some people owned dialog layout (.RC and resource editor), others message handlers, others DLL interfaces. The “GUI person” and the “engine person” became distinct roles.
Asynchronous feel: events could arrive in varied order; testing had to cover combinations. “Click A then B” vs. “Click B then A” could expose different bugs.
Toolchain fragmentation: resource compiler, different linker flags, different debugger workflows. Build breaks could occur in the resource step, which DOS-only developers had never seen.

Documentation shifted. Instead of “run main, then X, then Y,” teams wrote “on WM_COMMAND with ID Z, the flow is…”. Architecture diagrams showed window hierarchies and message flow, not just procedure call graphs. Onboarding documents included “Windows messaging basics” and “OWL object lifecycle.”

New joiners needed to internalize the event loop and the idea that “your code runs when Windows says so.” That was a larger conceptual jump than learning Object Pascal syntax. Experienced DOS Pascal developers sometimes struggled more than newcomers—unlearning “I control the flow” was harder than never having assumed it.

Code review practices adapted. DOS reviews often traced “what happens when we run.” Windows reviews asked “what happens when the user does X, and in what order do messages arrive?” Test plans shifted from “run through the menu” to “for each dialog, test each control, test tab order, test keyboard shortcuts.” The surface area of “things that can go wrong” grew substantially. Senior developers who had debugged DOS programs for years sometimes needed mentoring from junior developers who had started with Windows—not because the seniors were less skilled, but because the younger developers had never internalised the sequential model and adapted to event-driven design more quickly.

A practical collaboration upgrade in that period was formal handoff contracts between UI and engine work. In DOS-only projects, one developer could often own everything from input parsing to rendering. In TPW projects, that approach scaled poorly because message handlers, dialog resources, and shared core logic changed at different speeds. Teams that stayed healthy wrote explicit contracts:

which messages a form handled directly versus delegated
which unit owned validation rules
which module owned persistence and file I/O
which callbacks were synchronous, and which were deferred

Without this, “small UI tweaks” frequently broke core behavior because a developer moved logic into a handler that now ran under a different timing context.

Windows handoff note (example)
-----------------------------
Form: CustomerEdit
Owner: UI team

Incoming messages of interest:
  WM_INITDIALOG      -> initializes control state
  WM_COMMAND(IDOK)   -> calls ValidateCustomer, then SaveCustomer
  WM_CLOSE           -> prompts if dirty flag set

Engine callbacks:
  ValidateCustomer(Data): owned by core unit UCustomerRules
  SaveCustomer(Data): owned by storage unit UCustomerStore

Invariants:
  - SaveCustomer must never run before ValidateCustomer success
  - Dirty flag set only by control-change events
  - Cancel path must not mutate persisted data

This kind of document looked heavy for small teams and saved debugging days. It made expectations executable in reviews and reduced arguments about “who owns this behavior.” It also improved onboarding because a new developer could read one page and understand the current flow before touching code.

Another change was review vocabulary. DOS reviews asked, “Does this procedure return the right value?” Windows reviews increasingly asked, “In what callback context does this run?” and “What other message paths can trigger this state change?” That second question caught an entire class of defects: duplicated state transitions caused by one logic block being reachable through both menu commands and control notifications.

Teams that developed this callback-context discipline were already preparing for Delphi’s event model, even before switching products. The names changed (OnClick instead of WM_COMMAND branches), but the design concern stayed the same: keep state transitions explicit, idempotent where possible, and reviewable under multiple event paths.

Synthesis: what the toolchain taught

The transition from DOS Turbo Pascal to Object Pascal and TPW was not a language change alone. The Pascal syntax, unit system, and compilation model persisted. What changed was the execution environment, the artifact graph, and the problem-solving strategies. It was a shift in:

Control flow: from sequential to event-driven. Your code became a set of handlers invoked by the runtime, not a script you controlled from start to finish.
Artifacts: from .EXE+.OVR to .EXE+.DLL+resources. The artifact graph grew; build and deploy had more moving parts.
Debugging: from reproducible traces to message-flow analysis. Crashes became context-dependent; instrumentation and hypothesis replaced simple replay.
Deployment: from single-directory to multi-component, multi-profile. “Works on my machine” expanded to “works on which video driver, which memory configuration, which Windows patch level.”

The compiler and linker remained recognizable. The surrounding workflow— resources, callbacks, DLLs, deployment—became the new complexity. Teams that succeeded treated the Windows toolchain as a different system with different rules, not “Turbo Pascal with a new UI library.” The language carried forward; the problem-solving model had to adapt. Developers who made that mental shift were well positioned for Delphi and the 32-bit Windows world that followed. The lessons—event-driven design, resource pipelines, DLL boundaries—carried forward. Delphi refined the language and tooling, but the conceptual bridge from DOS to Windows had already been crossed.

Practical migration: DOS to Windows checklist

For teams porting an existing DOS application to Windows, a disciplined sequence reduced risk:

Isolate platform-dependent code. Identify all Dos, Crt, Graph, and overlay usage. Move them behind abstraction layers or {$IFDEF}-guarded units.
Verify string handling. Audit every place that touches filenames, user input, or API parameters. Introduce conversion routines and use them consistently.
Add the resource pipeline. Create a minimal .RC, link it, verify the app still runs. Add dialogs and menus incrementally.
Replace the main loop. The DOS “repeat until done” loop becomes “register, create, message loop.” Ensure no logic assumed it ran “at startup” in a single pass.
Test on multiple configurations. Different video drivers, different memory, and different Windows versions surfaced bugs that did not appear in development.

Not every DOS app was worth porting. Those that were tightly coupled to hardware (TSRs, direct port I/O, mode-X graphics) required substantial redesign or remained DOS-only. Business logic and data-heavy applications were better candidates.

A phased approach often worked: first a Windows shell that displayed data (perhaps read from a file format shared with the DOS version), then incremental feature parity. Trying to port everything at once usually led to long integration branches and merge pain. Teams that shipped a minimal Windows version early, then iterated, had better feedback and morale.

Full series index

Part 1: Anatomy and Workflow
Part 2: Objects, Units, and Binary Investigation
Part 3: Overlays, Memory Models, and Link Strategy
Part 4: Graphics Drivers, BGI, and Rendering Integration
Part 5: From 6.0 to 7.0 - Compiler, Linker, and Language Growth
Part 6: Object Pascal, TPW, and the Windows Transition (this article)
Part 7: From TPW to Delphi and the RAD Mindset

Turbo Pascal Toolchain, Part 7: From TPW to Delphi and the RAD Mindset

Fri, 13 Mar 2026 00:00:00 +0000

The transition from Turbo Pascal for Windows (TPW) and Borland Pascal 7 to Delphi was not merely a product upgrade. It was a mindset shift: from procedural resource wrangling and manual message dispatch to a visual, component-based, and event-driven workflow. Developers who had mastered TPW’s message loops and resource scripts found themselves in a different world—one where the form designer and object inspector replaced the resource editor, and where component ownership and event handlers replaced explicit handle management.

This article traces that transition from the perspective of a practitioner who lived it. It covers workflow changes, delivery model shifts, debugging adaptations, and team process evolution. The goal is not nostalgia but practical guidance: what to watch for when migrating, what patterns hold, and what pitfalls to avoid. The TPW-to-Delphi path was well-traveled in the mid-to-late 1990s; the lessons learned then remain applicable to any transition from low-level, imperative UI development to a higher-level, component-based framework. This article assumes familiarity with TPW or BP7; readers new to that era may find Part 5 and Part 6 of this series useful for context.

Structure map (balanced chapter plan)

To keep chapter quality even, the article uses a fixed ten-part structure before going deep into each topic:

historical grounding and chronology boundaries
what was at stake in workflow terms
form/resource workflow changes
component model and package mechanics
common migration culprits
build/release pipeline changes
testing/debugging mindset shift
architecture consequences
team-process and delivery-model changes
migration pattern playbook

Each chapter is intentionally expanded with similar depth: mechanism, pitfalls, and practical migration guidance.

Historical grounding: 1993–1996

Delphi development started internally at Borland around 1993. The first public release shipped in February 1995. That release introduced the Visual Component Library (VCL), which became the central framework for visual, event-driven Windows development in Object Pascal. Delphi 2 arrived in 1996 with a strong focus on 32-bit Windows, consolidating the shift away from 16-bit TPW.

These dates matter because they bound the technical assumptions. TPW and BP7 targeted 16-bit Windows. Delphi 1 supported 16-bit; Delphi 2 and later targeted 32-bit. Anyone migrating in that window faced both paradigm and platform shifts.

The competitive landscape also shaped expectations. Visual Basic had established a visual-design paradigm; Borland’s Object Windows Library (OWL) offered an object-oriented wrapper over the Windows API but remained close to the message model. Delphi positioned itself between the two: more structured than VB, more visual than raw OWL. The VCL was the differentiator—a single framework that unified visual design, component reuse, and compiled performance. Delphi 1 supported 16-bit Windows; migration from TPW could proceed without an immediate 32-bit requirement. Delphi 2’s 32-bit focus, arriving in 1996, aligned with Windows 95’s dominance and made the 16-bit path a legacy concern for most new development. The choice of Object Pascal rather than C++ for the VCL reflected Borland’s heritage and the language’s suitability for rapid development: a simpler object model, predictable destruction, and strong typing reduced certain classes of bugs. The trade-off was less low-level control than C++; for most business applications, that trade-off was acceptable. The result was a tool that appealed to both former TPW developers and newcomers from VB or other environments.

What was at stake: from resource wrangler to form designer

In TPW, you typically:

hand-authored or used resource editors to produce .RC and .RES files
wrote WndProc handlers and message-case logic
managed child window placement and styling via API calls
linked and loaded resources explicitly

The mental model was imperative: you told Windows what to do, step by step. Delphi replaced that with a declarative model: you placed components on forms, set properties, and responded to events. The form became the primary unit of design, not the resource file.

// TPW-era: manual dialog creation and message handling
function DlgProc(Dlg: HWND; Msg: Word; WParam: Word; LParam: LongInt): Bool;
begin
  Result := False;
  case Msg of
    WM_INITDIALOG: begin
      SetWindowText(GetDlgItem(Dlg, ID_EDIT), '');
      Result := True;
    end;
    WM_COMMAND:
      if LoWord(WParam) = IDOK then begin
        GetDlgItemText(Dlg, ID_EDIT, Buffer, SizeOf(Buffer));
        EndDialog(Dlg, IDOK);
        Result := True;
      end;
  end;
end;

In Delphi, the same interaction is expressed as component events:

procedure TMainForm btnOKClick(Sender: TObject);
begin
  // Edit1.Text is directly available; no GetDlgItemText
  ProcessInput(Edit1.Text);
  ModalResult := mrOK;
end;

The shift is not cosmetic. Ownership, lifecycle, and coupling all change. In TPW, you were responsible for ensuring that every control you created was eventually destroyed and that no dangling handles survived. In Delphi, the component tree and ownership model handle that—provided you used Create with the correct owner. The mental load shifted from “did I free everything?” to “did I wire the right events and set the right properties?”

A TPW developer who had internalized the message loop could predict exactly when WM_PAINT would fire and in what order. Delphi’s OnPaint and Invalidate abstracted that; the framework decided when to paint. That abstraction was liberating for routine UI work but could be frustrating when squeezing out performance or debugging flicker. Knowing when to drop to WndProc or CreateParams for low-level control became a mark of seniority. Double-buffering, which reduced flicker in TPW by managing WM_ERASEBKGND and paint regions, had VCL analogs (DoubleBuffered, TBitmap offscreen drawing), but the control points were different. Migration often required re-learning where the levers were. Developers who had tuned TPW apps for smooth animation or rapid repaints often needed to re-profile in Delphi: the VCL’s paint sequence and invalidation semantics were not identical to raw WM_PAINT handling. In most cases the default behavior was sufficient; for performance-critical paths, measuring before optimizing remained the rule.

Form and resource workflow changes

TPW projects combined Pascal sources with resource scripts. A typical layout:

MAIN.RC defined menus, dialogs, string tables
BRCC.EXE produced MAIN.RES
$R MAIN.RES pulled resources into the executable

Form layout was encoded in dialog templates. Moving a button meant editing coordinates in the .RC file or using a separate resource editor. Visual feedback was indirect. A typical TPW session might involve: edit .RC, run BRCC, recompile, run, discover the button was two pixels off, repeat. The compile-run cycle was fast, but the layout iteration was tedious.

Delphi introduced the .DFM (Delphi Form) file: a textual or binary representation of the form’s component tree and properties. The form designer and the form’s object inspector became the primary interface for layout and configuration. The .DFM is paired with a .PAS file that defines the component event handlers.

// Delphi unit: MainForm.pas (conceptual)
unit MainForm;

interface

uses
  Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs,
  StdCtrls;

type
  TMainForm = class(TForm)
    Edit1: TEdit;
    Button1: TButton;
    procedure Button1Click(Sender: TObject);
  private
    { Private declarations }
  public
    { Public declarations }
  end;

var
  MainForm: TMainForm;

implementation

{$R *.DFM}

procedure TMainForm.Button1Click(Sender: TObject);
begin
  ShowMessage('Value: ' + Edit1.Text);
end;

end.

The {$R *.DFM} directive embeds the form’s binary resource. No separate .RC file is needed for the form itself. Dialogs, menus, and layout live in the form file; the Pascal unit owns the behavior.

Early Delphi used binary .DFM by default. The format was compact but opaque; merging conflicts in version control were difficult. Later versions offered text-based .DFM, which improved diffability. Teams doing collaborative form work learned to prefer textual form storage where possible.

The form designer also changed the workflow for alignment and layout. Delphi provided alignment tools, snap-to-grid, and the ability to select multiple controls and align them as a group. This reduced the tedium of pixel-perfect placement and made iteration faster.

The object inspector and design-time behavior

A TPW developer edited resources in one tool and wrote Pascal in another. Delphi unified these: selecting a control in the form designer populated the object inspector with that control’s properties and events. Changing Caption or Enabled took effect immediately in the designer. Double-clicking an event slot (e.g. OnClick) created a stub handler and jumped to the code. This tight loop—design, set property, wire event, run—defined the RAD experience.

Design-time behavior rested on the same component instances that would run at runtime. A form loaded in the designer was a real TForm descendant with real children. Code that assumed a full application context (e.g. Application.MainForm) could fail in the designer. The csDesigning in ComponentState check became a standard guard for code that should run only at runtime. Custom components that performed I/O, showed dialogs, or accessed the network in their constructor needed such guards—otherwise the designer would hang or error when the component was dropped on a form.

The component model and packages

VCL is built on TComponent, which extends TPersistent and introduces ownership, naming, and streaming. Components can contain other components; they participate in design-time and runtime property streaming.

// Minimal custom component skeleton
unit MyButton;

interface

uses
  Classes, Controls, StdCtrls;

type
  TMyButton = class(TButton)
  private
    FClickCount: Integer;
  protected
    procedure Click; override;
  public
    constructor Create(AOwner: TComponent); override;
  published
    property ClickCount: Integer read FClickCount;
  end;

procedure Register;

implementation

constructor TMyButton.Create(AOwner: TComponent);
begin
  inherited Create(AOwner);
  FClickCount := 0;
end;

procedure TMyButton.Click;
begin
  Inc(FClickCount);
  inherited Click;
end;

procedure Register;
begin
  RegisterComponents('Samples', [TMyButton]);
end;

end.

Packages (.DPK) emerged as the unit of distribution for components and optional runtime modules. A package lists units and required packages; it can be design-time only, runtime only, or both. This allowed teams to ship component libraries without recompiling the main application. Design-time packages extended the IDE with new components and editors; runtime packages shipped as .BPL files and reduced application size when shared. The split meant that a bug fix in a shared component could be deployed by updating the BPL—if versioning was under control.

Third-party components and the ecosystem

Delphi’s component model encouraged a market for third-party controls: grids, charting, reporting, database-aware widgets. TPW had little equivalent; you built or hand-rolled most UI. Adopting a commercial component library accelerated development but introduced dependency risk. Components that assumed specific VCL versions, or used undocumented interfaces, could break on upgrade. Teams learned to evaluate components for stability and source availability, not just features. When a critical component was abandoned by its vendor, having the source often meant the difference between a fix and a rewrite.

// Example package source (.DPK)
package MyComponents;

{$R *.RES}
{$DESCRIPTION 'Custom component library'}

requires
  vcl;

contains
  MyButton in 'MyButton.pas';

end.

The component model also introduced the published keyword: properties declared published appear in the object inspector and are streamed to the .DFM. This is where design-time configuration meets runtime behavior.

Understanding the VCL hierarchy helped when extending or debugging components. TObject roots the tree; TPersistent adds streaming and ownership hooks; TComponent adds the component container model and design-time support; TControl adds visual representation and parent-child layout; TWinControl adds the Windows handle. When a form failed to paint or a control behaved oddly, tracing up this chain often revealed where the contract was violated.

// TForm inherits Handle, Parent, BoundsRect, Paint from TWinControl chain
// Override CreateParams, CreateWnd, WndProc for low-level customization
procedure TMyForm.CreateParams(var Params: TCreateParams);
begin
  inherited CreateParams(Params);
  Params.Style := Params.Style or WS_CLIPCHILDREN;
end;

Culprits and pitfalls during migration

Migration from TPW to Delphi was rarely a clean mechanical translation. The syntax was similar; the runtime model was not. Teams moving in that period encountered several recurring failure modes. Recognizing them early saved significant debugging time. What worked in TPW could fail subtly in Delphi, and the failures were often intermittent—dependent on timing, handle state, or initialization order.

Resource and handle confusion. TPW code often stored HWND or HMenu values and passed them to API calls. Delphi wraps these in component properties. Accessing the raw handle is still possible (Handle, Menu.Handle), but component lifetime now governs when that handle is valid. Code that cached handles across form recreate or destroy cycles could break.

Message loop assumptions. TPW applications sometimes relied on custom message loops or PeekMessage/GetMessage patterns. The VCL provides its own application message loop. Bypassing it or mixing models led to inconsistent behavior and hard-to-reproduce bugs.

String and type mismatches. TPW used ShortString by default. Delphi introduced AnsiString as the default string type (in 32-bit Delphi), with automatic memory management. Code that relied on length-byte semantics or passed strings to legacy APIs without conversion could fail.

// Pitfall: assuming ShortString semantics with AnsiString
procedure LegacyInterop;
var
  S: string;  // AnsiString in 32-bit Delphi
  Buf: array[0..255] of Char;
begin
  S := Edit1.Text;
  // Wrong: AnsiString is null-terminated, not length-prefixed
  // Right: StrPLCopy(Buf, S, High(Buf)); then use Buf for API calls
end;

Unit initialization order. Delphi units have initialization and finalization sections. Dependency order affects startup and shutdown. Circular unit references, or initialization that assumed a specific load order, could cause subtle crashes. A unit that allocated resources in initialization and freed them in finalization was generally safe—unless another unit’s initialization ran later and expected those resources to exist. Debugging startup crashes often meant tracing the unit load order in the project’s uses clause and the uses clauses of each unit. Circular references between units caused compile errors; circular logic in initialization (A init calls B, B init calls A) caused runtime failure. Breaking cycles by extracting shared code into a third unit, or deferring init to a later phase, was the standard fix.

Over-reliance on global state. TPW code often used global variables for form references and shared data. Delphi encourages form instances and component ownership. Migrating without refactoring globals led to re-entrancy and lifetime bugs.

Modal vs modeless confusion. TPW used DialogBox for modal dialogs and CreateWindow for modeless. Delphi’s ShowModal and Show map to that, but the timing of OnShow, OnActivate, and OnCreate differs from the raw API sequence. Code that assumed a specific order (e.g. painting before data load) could break. Testing both modal and modeless code paths was essential.

Integer and pointer size changes. In 16-bit TPW, Integer and Pointer were both 2 bytes (or 4 for far pointers). In 32-bit Delphi, Integer stayed 4 bytes but Pointer became 4 bytes in a flat address space. Code that stuffed pointers into Word or Integer for storage could truncate or corrupt. Using LongInt or Pointer explicitly for pointer-sized values avoided surprises.

RecreateWindow and handle invalidation. When a form’s RecreateWnd or similar mechanism ran (e.g. after changing BorderStyle or BorderIcons), the underlying HWND was destroyed and recreated. Code that cached the handle in a variable held a stale value. The pattern if HandleAllocated then before using Handle became a habit.

Build and release workflow

TPW builds were typically driven by the IDE or a small batch script that invoked the compiler and linker. Output was a single .EXE or .DLL. Delphi preserved that simplicity for many projects but added:

project files (.DPR) as the entry point
form units and {$R *.DFM} as first-class build inputs
package builds for component libraries
conditional compilation and build configurations

The project file (.DPR) replaced the old “main program” as the coordination point. It listed form units, marked which forms were auto-created (and thus loaded at startup), and could embed conditional compilation for different build targets. Auto-created forms simplified startup but could slow launch when many forms were created eagerly. Teams learned to create forms on demand (Form2 := TForm2.Create(Application); Form2.Show;) when memory or startup time mattered.

A minimal Delphi project:

program MyApp;

uses
  Forms,
  MainForm in 'MainForm.pas' {Form1};

{$R *.RES}

begin
  Application.Initialize;
  Application.CreateForm(TForm1, Form1);
  Application.Run;
end.

Command-line builds became DCC32.EXE (32-bit) or DCC.EXE (16-bit in Delphi 1). The linker (ILINK32 in 32-bit) consumed object files from the compiler; package references and external object modules were configured in the project or unit sources. Release builds often disabled debug info ($D-), local symbol info ($L-), overflow checking ($Q-), range checking ($R-), and stack checking ($S-). Teams learned to freeze these settings per configuration. Enabling checks in debug builds caught many bugs before they reached production; disabling them in release improved performance. The discipline was to fix any violation exposed by checks rather than disabling checks to silence the error. A build that succeeded with $R+ in one configuration and failed with it in another indicated a latent bug. Treating such failures as “the check is wrong” rather than “we need to fix the code” was a common but costly mistake. Range and overflow checks were cheap enough in debug that the performance argument against them rarely held.

The shift to 32-bit also meant larger executables and different deployment considerations—no more overlays, but more reliance on DLLs and packages for modular delivery. A typical build script might invoke DCC32 with -B (build all), -$D- (no debug info), and -$R- (no range check) for release. Staging the correct runtime packages (VCL*.BPL, RTL*.BPL) alongside the .EXE became part of the release checklist. The build pipeline itself was similar in spirit to TPW: compile units to object files, link to executable. The difference was scale—more units, form resources, and optional packages. Automated builds that had been simple batch files grew into scripts with conditional compilation, path setup, and post-build steps (e.g. version stamping, resource injection). Teams that delayed automation paid a tax during release cycles when manual steps were forgotten or executed in the wrong order.

// Project options often embedded in .DPR or a separate .CFG
// Conditional defines for build variants
{$IFDEF RELEASE}
{$D-} {$L-} {$Q-} {$R-} {$S-}
{$OPTIMIZATION ON}
{$ELSE}
{$D+} {$L+} {$Q+} {$R+} {$S+}
{$OPTIMIZATION OFF}
{$ENDIF}

Testing and debugging mentality shift

TPW debugging was breakpoint-and-inspect. You set breakpoints, stepped through WndProc and message handlers, and used the CPU view when things went wrong. The event model was explicit; you could trace from message to handler.

Delphi’s event-driven model changed the mental model. A button click did not map to a single linear path. Events could be chained (e.g. OnChange triggering further updates), and the call stack often included VCL framework code. Debuggers gained form-aware inspection: you could inspect the live form, its components, and their properties at breakpoints.

// Event-driven debugging: understand the call chain
procedure TForm1.Button1Click(Sender: TObject);
begin
  // Set breakpoint here; Sender tells you which button fired
  UpdateStatus;  // May trigger other events
end;

procedure TForm1.UpdateStatus;
begin
  // Breakpoint here to see who called UpdateStatus
  Label1.Caption := ComputeStatus;
end;

A recurring debugging scenario was “why did my form not update?” In TPW, you traced WM_PAINT or InvalidateRect. In Delphi, you checked whether Invalidate or Repaint was called, whether the control was visible, and whether OnPaint was overridden correctly. The data window (inspecting component properties at breakpoints) became as important as the watch window. Seeing that Label1.Caption was empty when you expected text, or that Edit1.Visible was False, often explained the bug without stepping through framework code.

The shift also encouraged a different testing approach: rather than exercising raw message paths, tests targeted event handlers and component state. Unit testing frameworks were rare in the mid-1990s, but the separation of event handlers from UI layout made it easier to reason about behavior in isolation.

When debugging failed, the CPU view remained the fallback. Crashes in VCL internals or third-party components often required setting a breakpoint on exceptions, then inspecting the call stack and registers. The “Evaluate/Modify” dialog let you execute expressions and change variables at breakpoints—useful for testing fixes without recompiling. Teams developed a habit of creating minimal reproduction cases: a blank form with one or two controls that exhibited the bug, stripped of application-specific logic.

Architecture implications

RAD and the VCL did not mandate architecture, but they pushed architects toward certain patterns. Teams that resisted sometimes paid a maintenance tax; teams that embraced them could scale. The framework rewarded specific ways of organizing code and penalized others.

Persistence and streaming. The VCL’s streaming system allowed forms and components to be saved and loaded without hand-written serialization. The TReader/TWriter and DefineProperties mechanism supported custom data in components. Component authors who needed to store non-published state could override DefineProperties to read and write their data. This was powerful but easy to get wrong—version mismatches between stored and current property semantics could corrupt form files. Defensive readers that checked version numbers or used try/except around property reads were common. Custom components that stored complex data (e.g. tree structures, graphs) had to decide whether to use DefineProperties or separate files. Embedded storage simplified deployment; separate files allowed formats that could be edited independently.

Event-driven design. Logic moved from a central message pump into distributed event handlers. This improved locality (each component owned its responses) but could scatter business logic across many handlers. Disciplined teams extracted core logic into service units or classes, keeping handlers thin. The Sender parameter in events allowed one handler to serve multiple controls (e.g. several buttons sharing an OnClick), but that pattern could obscure which control actually fired. Using separate handlers or if Sender = Button1 kept intent clear. The balance between DRY and readability was project-specific.

Threading and the main thread. The VCL was not designed for multi-threaded UI updates. Modifying control properties or calling UI methods from a worker thread could cause unpredictable crashes. The rule was: all UI updates must happen on the main thread. Synchronize and Queue (in later Delphi versions) marshaled work from background threads to the main thread. TPW code that had used worker threads for long operations had to be adapted to this model; the logic could stay in the thread, but any UI feedback had to go through Synchronize.

Separation of concerns. The form file (.DFM) held layout and property defaults; the Pascal unit held behavior. That split made it easier to version-control and merge changes, though .DFM binary format could be opaque. Later Delphi versions supported textual .DFM for clearer diffs. The separation also meant that a designer could adjust layout without touching code, and a developer could change behavior without risking layout. In practice, the split was porous—event handlers often reached into control properties, and layout could affect behavior (e.g. tab order, focus). But the ideal was clear: form for structure, unit for logic. Tab order in particular caused headaches: the designer set it visually, but adding or removing controls could scramble the intended flow. Using TabOrder explicitly, or the tab-order dialog, was part of the polish that separated finished applications from prototypes.

Component reuse and ownership. The Owner parameter in TComponent.Create established parent-child relationships. Destroying a form destroyed its components. This eliminated many manual cleanup bugs but required understanding ownership when creating components dynamically. Creating a control with nil as owner meant you were responsible for freeing it—a common source of leaks when the pattern was forgotten. The rule “always pass an owner when you have one” became second nature.

// Ownership: Created edit is owned by Form1, freed when Form1 is freed
procedure TForm1.AddDynamicEdit;
var
  E: TEdit;
begin
  E := TEdit.Create(Self);  // Self = Form1 = owner
  E.Parent := Self;
  E.Top := 10;
  E.Left := 10;
  E.Text := 'Dynamic';
end;

Dependency direction. Well-structured Delphi projects kept business logic in units that did not depend on Forms or Controls. UI units depended on business units, not the reverse. This preserved testability and reuse.

// Good: business logic unit has no UI dependency
unit OrderLogic;

interface
function ValidateOrder(const OrderId: string): Boolean;

implementation
// No Forms, Controls, or Graphics
end.

// UI unit depends on OrderLogic
unit OrderForm;

uses
  ..., OrderLogic;

procedure TOrderForm.btnValidateClick(Sender: TObject);
begin
  if ValidateOrder(edtOrderId.Text) then
    ShowMessage('Valid');
end;

Form bloat. A common anti-pattern was the “god form”: one form with dozens of controls and thousands of lines. Splitting into sub-forms, frames (when available), or tabbed interfaces required discipline. The RAD temptation was to keep adding controls; the architectural response was to extract coherent panels into separate units.

Data binding and the missing link. Early Delphi did not ship a formal data-binding framework. Developers manually moved data between controls and business objects in event handlers. The pattern “read from controls, validate, update model, write back to controls” was common. This worked but scattered synchronization logic. Third-party data-aware controls and later framework additions addressed some of this; disciplined teams often built thin adapter layers to centralize the binding logic.

Delivery model and team process changes

The RAD promise was faster delivery. The reality was more nuanced.

TPW projects often had a single developer or a small team with clear handoffs: one person owned resources, another owned logic. Delphi’s RAD workflow encouraged faster iteration. A developer could design a form, wire events, and see results without leaving the IDE. That accelerated prototyping but also tempted teams to skip design—“we’ll fix it later” became a common anti-pattern.

Delivery cycles shortened. Demo builds could be produced in hours. The flip side was technical debt: forms with hundreds of controls, event handlers doing too much, and little automated testing. Teams that adopted coding standards (handler size limits, mandatory extraction of business logic) fared better.

When RAD went wrong, the symptoms were familiar: a form that “worked” until you changed one thing and then everything broke; event handlers that called each other in circular ways; business logic embedded in OnClick that could not be tested without spinning up the full form. The remedy was the same as in non-RAD projects—extract, decompose, test—but the temptation to stay in “fast mode” was stronger because the IDE made it easy to keep adding. Senior developers learned to recognize the moment when a form or handler had crossed the complexity threshold and needed refactoring.

Distribution also changed. TPW produced a standalone .EXE plus any DLLs. Delphi could do the same, but package-based deployments (runtime packages like VCL50.BPL) allowed smaller executables and shared framework updates. The trade-off was versioning: mismatched package versions caused load failures. “DLL hell” extended to packages: installing a new application could overwrite shared BPLs and break existing ones. Many teams chose static linking for distribution to avoid that risk.

Team roles shifted. The “resource person” role diminished; the “form designer” and “component author” roles emerged. Code reviews began to ask “is this handler too large?” and “should this logic live in a service unit?” Pair programming, where it existed, often involved one person driving the form designer while the other focused on event logic and backend integration. The division was natural: layout and property wrangling on one side, data flow and validation on the other. Teams that formalized this split—e.g. “form designer” and “form programmer” roles—sometimes produced cleaner boundaries than those where one person did everything. The risk was handoff friction when the designer’s intent was not clear from the form alone.

Practical migration patterns

When porting TPW code to Delphi, these patterns proved reliable.

Extract message handlers into event-like procedures. Wrap the core logic in a procedure with clear parameters; call it from both the old WndProc path and the new event handler during transition.

procedure DoProcessInput(const AText: string);
begin
  if Trim(AText) = '' then Exit;
  // Core logic here
end;

// TPW: call from WM_COMMAND handler
// Delphi: call from Button1Click with Edit1.Text

Introduce form classes gradually. Start with a blank form, add controls one at a time, and move logic from global procedures into form methods. This avoids big-bang rewrites. Resist the urge to convert all dialogs in one pass. Pick the simplest dialog first, migrate it, validate, then proceed. Each successful migration builds confidence and surfaces patterns that apply to the next.

Create a compatibility shim for shared code. If both TPW and Delphi executables need to call the same business logic during transition, extract that logic into a unit with no UI dependencies. Both projects can use it. Pass data via parameters, not globals. This keeps the migration reversible and reduces the risk of fork drift. The shim unit should avoid VCL-specific types where possible; use plain Pascal types (string, Integer, records) for interfaces that cross the TPW/Delphi boundary.

Verify string and API compatibility. Use StrPLCopy and StrPCopy when passing strings to Windows API. Check PChar vs PAnsiChar in 32-bit Delphi. Test with empty strings and long strings; ShortString and AnsiString differ at the boundaries.

// Safe API string passing
procedure SafeAPICall(const S: string);
var
  Buf: array[0..259] of AnsiChar;
begin
  StrPLCopy(Buf, AnsiString(S), High(Buf));
  SomeAPI(@Buf[0]);
end;

Lock build configuration early. Decide debug vs release, range check on/off, and optimization level. Document and automate. Avoid ad hoc changes during release crunches.

Migration checklist. A practical sequence:

1. Inventory TPW dialogs and main windows; map each to a target form.
2. Create empty forms, add controls to match layout, wire stub events.
3. Move message-handler logic into event handlers; extract shared logic.
4. Replace global form references with Application.FindComponent or parameters.
5. Audit string types at API boundaries; add StrPLCopy/StrPCopy where needed.
6. Run under range checking and overflow checking; fix violations first.
7. Test modal/modeless behavior; verify focus and activation order.
8. Freeze build options; document and script the release build.

Use Application.OnMessage sparingly. The global message hook can help during migration to intercept specific messages, but it runs for every message and can obscure the event-driven flow. Prefer component-level overrides or message handlers (TForm supports WM_* procedure declarations) for targeted handling.

// Form-level message handler: more targeted than Application.OnMessage
type
  TMainForm = class(TForm)
  private
    procedure WMUserMsg(var Msg: TMessage); message WM_USER;
  end;

procedure TMainForm.WMUserMsg(var Msg: TMessage);
begin
  // Handle custom message; call inherited for default behavior if needed
  ProcessCustomMessage(Msg.WParam, Msg.LParam);
end;

Preserve TPW project artifacts during transition. Keep a known-good TPW build and its sources in version control. If a Delphi regression appears, you can compare behavior and isolate whether the bug is in migrated logic or the new framework. When the migration is complete, archive rather than delete—historical reference has value for onboarding and retrospective analysis.

Treat the first migrated dialog as a prototype. Use it to establish conventions: naming (e.g. btnOK not Button1), handler structure, where validation lives. Document those conventions and apply them consistently. The first migration is always the hardest; later ones benefit from the patterns you extract. Skipping the documentation step means each developer reinvents the approach, and inconsistency makes maintenance harder.

Expect a learning curve for the form designer. TPW developers who had never used a visual designer faced new concepts: alignment palettes, tab order, anchor and alignment properties (in later Delphi versions), the difference between selecting the form and selecting a control. Spending a few hours on throwaway forms to learn alignment, anchoring, and the property inspector paid off before tackling a real migration. Misunderstanding the designer led to layout bugs that were hard to fix by hand-editing .DFM.

First 90-day Delphi adoption cadence

Teams that transitioned cleanly usually followed a staged first-quarter plan, not an all-at-once rewrite:

Days 1-30:
  - pick one medium-complex form
  - define naming/event conventions
  - establish build options and debug baseline

Days 31-60:
  - migrate 3-5 related dialogs/forms
  - extract shared non-UI logic into units
  - add regression checklist for core user flows

Days 61-90:
  - package reusable controls/components
  - document standard form lifecycle hooks
  - formalize release checklist and rollback criteria

This cadence solved two chronic problems: premature abstraction and duplicated mistakes. Premature abstraction happened when teams designed a full internal “framework” before they had migrated enough screens to understand recurring patterns. Duplicated mistakes happened when each developer migrated forms in isolation with personal conventions. A short, staged cadence turned both into manageable process work.

A practical metric during this period was “time from UI change request to tested build.” If that time dropped while defect rate stayed stable, Delphi adoption was producing value. If the time dropped but defect rate climbed, the team was moving too fast without enough shared conventions.

Summary and outlook

The TPW-to-Delphi transition was more than a product upgrade; it was a paradigm shift in how Windows UI was built: from imperative, resource-centric Windows development to a visual, event-driven, component-based model. VCL and the form designer changed how developers conceived of UI, and the RAD mindset changed delivery expectations. Teams that understood both the gains (faster iteration, clearer ownership, component reuse) and the pitfalls (handle lifetime, string types, over-coupled forms) navigated the transition successfully.

Delphi’s influence extended beyond Borland. The component model, property inspector, and form designer pattern appeared in other tools and languages. The Object Pascal language evolved but remained recognizable to TPW practitioners. For those tracing the Turbo Pascal toolchain into the Windows era, Delphi is the natural continuation—and the RAD mindset it introduced still shapes how many think about UI development today. The move from “write code that creates UI” to “design UI and write code that responds” has informed every major GUI framework since.

The transition also illustrated a recurring tension in tool evolution: each abstraction layer buys productivity at the cost of opacity. TPW developers could read the SDK and understand every message; Delphi developers relied on the VCL to do the right thing. When the abstraction leaked—handle lifetime, recreate behavior, focus management—the ability to reason about the lower level became valuable. The best Delphi practitioners kept that mental model intact. They knew when to use Sender in an event to identify the originating control, when to override WndProc versus using OnMessage, and how to trace from a visible bug back through the message or event chain. That knowledge, built during the TPW-to-Delphi transition, remained valuable for as long as Windows and the VCL evolved together.

Turbo Pascal History Through Tooling Decisions

Sun, 22 Feb 2026 00:00:00 +0000

People often tell Turbo Pascal history as a sequence of versions and release dates. That timeline matters, but it misses why the tool changed habits so deeply. The real story is tooling ergonomics under constraints: compile speed, predictable output, integrated editing, and a workflow that kept intention intact from keystroke to executable.

In other words, Turbo Pascal was not only a language product. It was a decision system.

Why that era felt so productive

The key loop was short and visible:

edit in integrated environment
compile in seconds
run immediately
inspect result and repeat

No hidden dependency graph. No plugin negotiation. No remote service in the critical path. This reduced context switching in ways modern teams still struggle to recover through process design.

The historical importance is not nostalgia. It is evidence that feedback-loop economics shape software quality more than fashionable architecture slogans.

Distribution shaped engineering choices

In floppy-era ecosystems, distribution size and hardware variability were not side concerns. They drove design:

smaller executables reduced install friction
deterministic startup mattered on mixed hardware
clear error paths mattered without telemetry backends

Turbo Pascal’s model rewarded explicit interfaces and compact runtime assumptions. Teams that wanted software to survive wild machine diversity had to be precise.

Unit system as collaboration contract

Turbo Pascal units gave teams strong boundaries without heavy ceremony. A unit interface section became a living contract, and the implementation section held the details. This mirrors modern module design principles, but with less boilerplate and fewer moving parts.

unit ClockFmt;

interface
function IsoTime: string;

implementation
function IsoTime: string;
begin
  IsoTime := '2026-02-22T12:34:56';
end;

end.

Simple pattern, strong effect: contracts became visible and stable.

Build behavior and trust

One under-discussed historical factor is trust in the build result. Turbo Pascal gave developers strong confidence that what compiled now would run now on the same target profile. This reliability reduced defensive ritual and encouraged experimentation.

When build systems are unpredictable, teams compensate with process overhead: additional reviews, duplicated staging checks, expanded manual validation. Predictable tooling is not just convenience; it is organizational cost control.

Debugging as craft, not ceremony

Classic debugging in this ecosystem leaned on watch windows, deterministic repro paths, and explicit state inspection. Because the runtime stack was smaller, developers were closer to cause and effect. Failures were painful, but usually legible.

That legibility is historically important. It built strong mental models in generations of engineers who later carried those habits into network systems, embedded work, and security tooling.

What modern teams can still steal

You do not need to abandon modern stacks to learn from this:

optimize for short local feedback loops
keep module contracts obvious
reduce hidden build indirection
separate policy from mechanism in config files
document assumptions where runtime variability is high

These are the same themes behind Clarity Is an Operational Advantage and Terminal Kits for Incident Triage, just seen through retro tooling history.

Tooling history as systems history

Turbo Pascal’s relevance endures because it compresses essential engineering lessons into a small environment:

architecture is influenced by tool friction
reliability is influenced by startup discipline
collaboration quality is influenced by interface clarity
speed is influenced by feedback-loop latency

Those lessons are historical facts and current strategy at the same time.

Practical way to study it now

If you want something concrete, recreate one small project with strict boundaries:

one executable
three units max
explicit config file
measured compile-run cycle
one regression checklist file

Then compare your decision speed and bug triage quality against a similar modern project. Treat this as an experiment, not ideology.

Cross-reference starting points:

History is most useful when it changes present behavior. Turbo Pascal still does that unusually well because the system is small enough to understand and strict enough to teach.

A useful closing exercise is to measure your own feedback loop in minutes, not feelings. When teams quantify loop time, tooling discussions become clearer and less ideological.

Turbo Pascal Toolchain, Part 1: Anatomy and Workflow

Sun, 22 Feb 2026 00:00:00 +0000

Turbo Pascal is remembered for a fast blue IDE, but that is only the surface. The real strength was a full toolchain with tight feedback loops: editor, compiler, linker, debugger, units, and predictable artifacts. Part 1 maps that system in practical terms before we dive into binary formats, overlays, BGI, and ABI-level language details.

Structure map. This article proceeds in twelve sections: (1) version and scope boundaries, (2) toolchain topology and component wiring, (3) artifact pipeline and engineering signal, (4) IDE options as architecture, (5) directory and path policy, (6) practical project layout, (7) IDE–CLI parity and reproducible builds, (8) units as compile boundaries and incremental strategy, (9) debug loop mechanics and map/debug workflow, (10) external objects and integration discipline, (11) operational checklists and failure modes, and (12) how this foundation supports the rest of the series.

Scope and version boundaries

When discussing “latest Turbo Pascal,” engineers usually mean Turbo Pascal 7.0 and, in many setups, Borland Pascal 7 tooling around it. Some executable names and switches vary by package and installation, so this article uses two rules:

describe workflow and architecture in version-stable terms
call out where command names or options may differ

That keeps the discussion accurate without pretending all distributions are identical. TP 5.x used a simpler unit format; TP 6 and 7 extended it with object-oriented support and richer metadata. Projects that must support both TP 5 and TP 7 need to avoid OOP extensions and test on both toolchains.

Technical mechanism. TP 7 and BP 7 share the same core compiler engine but differ in packaging: TURBO.EXE (IDE) vs BP.EXE (Borland Pascal IDE), and command-line variants such as TPC.EXE or BPC.EXE. The compiler emits .TPU (Turbo Pascal Unit) files or .OBJ for linkable object code; TP 5.x and TP 6.x used similar conventions with minor format changes. Knowing your actual binary set (dir *.exe in the TP install directory) prevents configuration mistakes.

Workflow impact. Version drift between machines—one developer on TP 6, another on BP 7—manifests as mysterious “unit version mismatch” or link errors that do not reproduce elsewhere. Pitfall: assuming TURBO.EXE and TPC.EXE on the same install are always in lockstep; some bundled distributions ship slightly different compiler builds. Practical check: run tpc -? (or equivalent) and note the version string; document it in project setup. If multiple TP installs exist (e.g. C:\TP and C:\BP), ensure PATH and project scripts point to one canonical location to avoid picking up the wrong compiler.

Toolchain topology (what talks to what)

At minimum, a project involves these moving parts:

TURBO.EXE or BP.EXE style IDE workflow
command-line compiler (TPC in many setups)
linker stage (often via TLINK)
optional assembler and object modules (TASM plus .OBJ)
optional library manager (TLIB)
dump/inspection tooling (TDUMP)

Even if you only press “Compile” in the IDE, these layers still exist. Knowing them separately is the difference between “works today” and “I can debug this under pressure.”

Technical mechanism. The IDE invokes the compiler internally; the compiler produces .TPU or .OBJ and hands off to TLINK to produce the final .EXE. You rarely invoke TLINK directly—the compiler drives it. Understanding the handoff helps when TLINK fails: check that all referenced OBJ and TPU files exist and that no path is wrong. When you add {$L FASTBLIT} for an assembly module, the compiler embeds a call to TLINK with the listed object files. TASM is invoked separately if you maintain .ASM sources; TLIB merges .OBJ into .LIB archives for reuse. TDUMP inspects .EXE, .OBJ, and .TPU headers and symbol tables—critical when a link fails and you need to verify what the compiler actually produced.

Build loop semantics. Each “Compile” in the IDE runs the compiler on the main program; the compiler in turn recompiles any unit whose .PAS is newer than its .TPU, then invokes TLINK. If nothing changed, a second Compile is effectively a no-op unless you forced a rebuild—but “nothing changed” depends on timestamps. Editing a file and reverting without saving leaves the .PAS older than the .TPU, so the compiler skips it. Conversely, touching a unit file (e.g. via a script) forces recompile even when source is unchanged. Some installs exposed a “Build” vs “Make” distinction: Make recompiles only changed modules; Build recompiles everything. The command-line tpc typically behaves like Make. Knowing which mode you are in avoids confusion when expectations differ (“I changed that!” vs “it didn’t rebuild”).

Workflow impact. Debugging a “Compiler Error” when the real failure is at link time wastes hours. Learn to read compiler vs linker messages: TP compiler errors cite source lines; TLINK errors cite missing symbols or object format issues. When you add {$L file}, the compiler does not run TASM—you must assemble .ASM to .OBJ yourself. A project using assembly typically has a two-step build: first tasm /mx module, then tpc main.pas. Omitting the TASM step produces “cannot open file” or “invalid object file” from TLINK. Pitfall: the IDE may hide TLINK output or truncate it; a batch build that echoes full output is essential. Practical check: run a minimal tpc main.pas from the command line and observe the exact sequence of invocations and any warnings; compare with IDE compile to spot divergence. When TLINK reports “undefined symbol,” use tdump main.obj | findstr SYMBOL to inspect what the compiler actually exported; cross-reference with the unit’s interface to find mismatches. TDUMP also reveals TPU structure—run tdump unit.tpu to see exported symbols and segment names when debugging circular unit references or missing exports.

Artifact pipeline as engineering signal

A typical single-target flow:

1
2

.PAS  --compile-->  .TPU/.OBJ  --link-->  .EXE
                              \--optional--> .MAP

Extended flows add .OVR (overlay file), .BGI/.CHR assets (Graph unit path), and linked external .OBJ modules. If output behavior is surprising, artifacts are your first ground truth, not intuition. Runtime paths for BGI and overlays must match deployment layout—developing with assets in-project but shipping an EXE alone causes silent failures at InitGraph or overlay load.

Technical mechanism. Each .PAS file compiles to an intermediate form: main-program .PAS → .OBJ (or directly to .EXE when TP drives TLINK); unit .PAS → .TPU. The compiler emits one OBJ per main program and one TPU per unit; the linker then combines them. Multi-module programs (e.g. a main that uses several units) produce one EXE that embeds all linked code. The linker merges one or more .OBJ plus referenced .TPU content into a single executable. A .MAP file is produced when you pass /M (or equivalent) to the linker—it lists segment layout, public symbols, and program start address. Overlays (.OVR) are built separately and loaded at runtime by the overlay manager.

Map file usage. The map lists segments (e.g. CODE, DATA, BSS) with their load addresses and sizes, followed by a public symbol table with segment:offset for each symbol. A crash address like 0x1234:0x5678 maps to a routine by finding the segment name, then scanning the symbol list for the highest address ≤ 0x5678 within that segment—that typically identifies the containing procedure. Segment layout can shift between builds (e.g. when adding units or changing optimization), so the map must match the exact binary being debugged. Keep dated copies (MAIN_20260222.MAP) for shipped builds so a user crash report from that date can be correlated.

Workflow impact. When the program crashes at startup or behaves differently on another machine, the .MAP file tells you where symbols landed in memory—essential for correlating debug output or crash addresses. Pitfall: stale .TPU files: a unit’s interface changed but some dependent unit still compiled against an old .TPU, producing subtle ABI drift. Practical check: before release, delete all .TPU and .OBJ, rebuild from scratch, and verify no “unit version” or “identifier not found” surprises. For overlay builds, the .OVR is produced by a separate invocation; confirm the overlay manager path matches where you place the .OVR at runtime.

IDE settings are architecture settings

Turbo Pascal options are often treated as editor preferences. They are not. They directly alter generated code and runtime behavior:

debug info and symbolic visibility
optimization strategy
stack/heap constraints
runtime checking behavior (range, overflow, I/O)
code generation assumptions (CPU/FPU target profile)

Disciplined teams freeze these as named build profiles (for example: debug, release, diag) and log intentional changes.

Technical mechanism. Options like {$D+} (debug info), {$O+} (overlay support), {$R+} (range checking), and {$S+} (stack checking) are compiler directives; the IDE also stores numeric settings (heap size, stack size, target CPU) in its configuration. These feed into code generation and linker arguments. A “release” build typically turns off {$D+} and {$R+}, enables {$O+} if using overlays, and may bump optimization.

Workflow impact. Switching profiles mid-project without documenting the change leads to “works on my machine” when one developer runs a debug build and another ships a release build—different memory layout and checking can hide or expose bugs. Heap and stack size (configurable in Linker options or via $M directive) affect how much data and recursion the program can handle; a release build with reduced heap may expose allocation failures that a development build with generous limits never showed. Pitfall: TP stores options in .TP project files or in the default configuration; a fresh clone may pick up system defaults instead of project-specific values. Check-in a .TP file only if the team agrees; otherwise, source-level directives are safer and travel with the code. Practical check: maintain a BUILD.CFG (or equivalent) or inline directives at the top of MAIN.PAS that explicitly set the profile, e.g. {$D+,R+,S+} for debug and {$D-,R-,S-} for release. A minimal BUILD.CFG can list one directive per line; the compiler reads it before source. Alternatively, use a single CONFIG.PAS that each main program and test uses first, so the profile is always in version control. The $M directive sets stack and heap: {$M stacksize, heapsize, maxheapsize}. Too-small heap causes “Out of memory” at runtime; too-small stack breaks deep recursion or large local arrays.

Directory and path policy (where projects fail first)

Most hard-to-reproduce TP failures are path/config drift:

unit search path differs between machines
object search path misses external assembly objects
include path resolves wrong file version
runtime asset path misses .BGI/.CHR/.OVR

A stable project keeps paths explicit in one place and checks them at startup. Do not rely on “whatever current directory happens to be.”

Technical mechanism. TP resolves units and includes in a fixed order: current directory first, then paths from Options | Directories (or -U / -I on the command line). The order matters: if C:\TP\UNITS and C:\PROJECT\UNITS both exist, whichever is searched first wins. Object files ({$L file}) are resolved relative to the source file or the object path. Runtime paths (BGI, fonts) are handled by the Graph unit and typically use InitGraph’s driver path or SetGraphBufSize; the program must know where its asset directory lives.

Workflow impact. A developer who runs TP from C:\PROJECT\SRC gets different resolution than one who runs from C:\PROJECT—units in SRC\ may be found first, masking a missing path. Pitfall: PATH and SET in AUTOEXEC.BAT vary by machine; a batch build that does cd \PROJECT\SRC before invoking tpc can behave differently from an IDE launched from a shortcut with a different working directory. Practical check: add a startup check in MAIN.PAS that verifies a known file exists (e.g. ASSETS\BGI\EGAVGA.BGI) and aborts with a clear message if not found; document the required directory layout in README. Use ParamStr(0) to derive the executable location and build asset paths relative to it when possible—that helps when the user runs from a different directory. Example guard at the top of a graphics-heavy main:

{$I-}
assign(f, 'ASSETS\BGI\EGAVGA.BGI');
reset(f);
if IOResult <> 0 then begin
  writeln('FATAL: BGI path not found. Run from project root.');
  halt(1);
end;
close(f);
{$I+}

This fails fast instead of letting InitGraph return a cryptic error code.

TP5 reference details worth remembering:

System unit is used automatically; other standard units are not.
non-resident units are resolved by <UnitName>.TPU search (current dir, then configured unit directories).
make/build unit source lookup follows the same pattern with <UnitName>.PAS. On the command line, tpc -Upath1;path2 -Ipath3 sets unit and include paths; semicolon separates multiple entries. Paths are searched in order. Relative paths are interpreted from the current directory at invoke time—another reason to standardize cd before build.

Path resolution behavior. {$I filename} (include) and {$L filename} (link object) resolve differently. Include files are searched along the include path and typically use just the base name ({$I TYPES.INC}); the compiler merges the file contents at that point. Object files for {$L} are usually resolved relative to the source file’s directory first, then the unit/object path. Using a bare name like {$L FASTBLIT} assumes FASTBLIT.OBJ is in the same directory as the .PAS or on the object path. A common pitfall: a unit in SRC\CORE.PAS with {$L ..\ASM\FASTBLIT} works when compiled from project root, but a different working directory can break resolution. Prefer explicit paths in build configuration (-U, -I, object path) over {$L} with relative names when the source tree spans multiple directories. Paths containing spaces (e.g. C:\TP\My Units) can cause parsing issues in some older TP installs; stick to 8.3 names in critical paths when possible.

Practical project shape

PROJECT/
  SRC/
    MAIN.PAS
    CORE.PAS
    RENDER.PAS
  ASM/
    FASTBLIT.ASM
    FASTBLIT.OBJ
  BIN/
  ASSETS/
    BGI/
  BUILD.BAT
  README.TXT
  CHANGELOG.TXT

This looks mundane. That is good. In DOS projects, boring layout is a stability feature.

Technical mechanism. SRC/ holds all .PAS; ASM/ holds assembly source and pre-built .OBJ; BIN/ receives .EXE, .OVR, .MAP; ASSETS/BGI/ holds driver and font files. The compiler’s -E (or equivalent) switch can direct output to BIN\. Keeping .TPU alongside source in SRC\ or in a dedicated UNITS\ subdirectory avoids polluting the root. A UNITS\ folder with only TPUs (no PAS) works if you treat it as build output—the batch compile writes TPUs there and adds -U%CD%\UNITS so dependents find them. This keeps SRC clean of generated files.

Workflow impact. A flat layout with everything in the project root works for tiny projects but becomes unmaintainable when units and assets multiply. Pitfall: storing .TPU in a shared C:\TP\UNITS risks cross-project contamination—two projects with a UTILS unit will overwrite each other’s TPU. Practical check: the batch build should cd to a canonical directory (e.g. project root), set TPC output and unit paths explicitly, and produce deterministic artifacts in BIN\; dir BIN\*.exe after build should show expected output with sensible timestamps. A clean-build target in the batch helps catch stale-artifact bugs:

:clean
del /q SRC\*.TPU 2>nul
del /q SRC\*.OBJ 2>nul
del /q ASM\*.OBJ 2>nul
del /q BIN\*.* 2>nul
echo Cleaned
goto :eof

Invoke with BUILD.BAT clean before a release build. If the batch supports arguments, add if "%1"=="clean" goto clean at the top so build clean and build both work from a single script.

IDE and CLI parity is non-negotiable

If a project only builds via hidden IDE state, you do not have a reproducible build. Keep a batch build path next to the IDE path.

@echo off
setlocal
set MAIN=SRC\MAIN.PAS
rem command/options vary by TP/BP install; -E directs exe to BIN
set TPCDIR=C:\TP
set PATH=%TPCDIR%;%PATH%
cd /d %~dp0
tpc %MAIN% -U%CD%\UNITS -EBIN
if errorlevel 1 goto fail
echo BUILD OK
goto end
:fail
echo BUILD FAILED
:end
endlocal

Technical mechanism. tpc (or bpc) accepts -U for unit search path, -E for exe output directory, -D for defines, and -$ for directives. Exact syntax varies; BP 7 uses -Upath and -Epath (no space between switch and path). The batch file uses cd /d %~dp0 to ensure it runs from the project root regardless of where it is invoked. Some installs use -Epath to send the EXE to a specific directory; without it, the EXE lands next to the main source, which can clutter SRC\.

Workflow impact. When the IDE build succeeds but the batch fails (or vice versa), the difference is usually in paths or options. Pitfall: the IDE may use a different TPC than the one on PATH if the shortcut sets its own environment. Practical check: add tpc %MAIN% 2>&1 | more to capture full compiler/linker output; compare character-for-character with IDE compile log if behavior diverges. Expected outcome: success yields deterministic .EXE in BIN\; failure yields non-zero exit and repeatable error output.

Units are compile boundaries, not just reuse

Units define contracts and incremental rebuild boundaries. This yields two benefits:

interface changes produce immediate compile-time blast radius
implementation-only changes stay local when boundaries are clean

That behavior gives architectural feedback automatically. If tiny edits trigger massive recompilation or link churn, boundaries are weak.

Technical mechanism. A unit’s interface section is compiled first and emitted into the .TPU; dependents read that interface. Changing the interface (adding/removing/altering exported declarations) invalidates all dependent units—they must recompile. Changing only the implementation invalidates only that unit’s TPU. The compiler tracks dependency via timestamps (or explicit make rules) and recompiles only what changed.

Workflow impact. A well-factored project compiles quickly during development: edit one unit’s implementation, only that unit rebuilds. Interface changes are expensive by design—they force you to confront coupling. Pitfall: large “god” units with sprawling interfaces cause rebuild cascades; splitting into smaller units with narrow interfaces reduces blast radius. Practical check: run a clean build, make a one-line implementation change, rebuild—only that unit’s TPU should change. If half the project rebuilds, revisit boundaries. Incremental compile strategy: without make, TP recompiles a unit when its .PAS is newer than its .TPU. Compile in dependency order (leaf units first) or rely on uses order; some teams kept a batch that compiled units explicitly before the main program to avoid timestamp quirks. See also: Turbo Pascal Units as Architecture, Not Just Reuse.

Debug loop mechanics

A strong TP debugging loop is short and explicit:

define expected behavior before run
run the same deterministic input
inspect state at subsystem boundaries
adjust one variable or one assumption
rerun same case

Fast compile-run cycles make this practical dozens of times per hour. That is why teams felt productive: not because bugs were fewer, but because feedback latency stayed low.

Technical mechanism. TP’s integrated debugger uses {$D+} (debug info) and {$L+} (local symbol info) to map source lines to addresses. The linker’s map file (/M or $M output) lists segment:offset for public symbols. When a crash occurs at a hex address, you look up that address in the map to identify the routine. TD (Turbo Debugger) can attach to a running process or launch the program with breakpoints; TD requires the same debug info and matching source paths.

Workflow impact. A typical cycle: set breakpoint in TD, run, inspect variables, fix source, recompile, run again. TD can be launched from the command line with td main.exe or from the IDE’s Run menu; ensure the working directory is set so the program finds its assets. Without a map file, a crash dump (e.g. from a user) is useless—you cannot map the fault address back to a function.

Map/debug workflow. When a user reports “it crashed at 1234:5678,” the workflow is: (1) obtain the exact EXE they ran—rebuilding from “same source” may produce different segment layout; (2) ensure you have the matching map from that build; (3) parse the address: segment 1234 hex, offset 5678 hex; (4) open the map, locate the segment (often CODE or C0), find the symbol with the largest address ≤ 5678 in that segment—that is the containing routine; (5) open that routine in the source and reason about what could fault at that offset. TD’s “View | CPU” shows disassembly; correlating the fault address with the map gives you the Pascal routine to inspect. If debug info was stripped (release build), you still have the map for symbol-level localization; line numbers require {$D+} and {$L+} in the binary. Some teams kept a post-build step that copied MAIN.EXE and MAIN.MAP to a RELEASE\ folder with a date suffix, so crash reports could be matched to archived symbol data.

Pitfall: debug builds with {$D+} produce larger executables and slightly different code layout; a bug that appears only in release may be a timing or memory-layout issue. Practical check: keep a debug build profile that always generates .MAP, and ensure your run script or batch uses that profile when investigating crashes. Example map lookup: findstr /C:"RoutineName" MAIN.MAP to locate a symbol’s segment. Team checklist: (1) every developer runs tpc -? and records version in project docs; (2) new machines run a clean build before first commit; (3) before release, one developer performs a memory-stressed boot (load COMMAND.COM, a few TSRs, then run) to catch conventional-memory edge cases. (4) When integrating assembly or C modules, one person owns the calling-convention doc and reviews any new external declarations. (5) Archive the exact BUILD.BAT and BUILD.CFG (or equivalent) with each shipped build so you can reproduce it later.

External objects from day one

Many real projects mixed Pascal with assembly or C object modules. Keep that integration explicit:

source ownership (.ASM/.PAS) is documented
object generation step is reproducible
calling convention assumptions are written next to declarations

Technical mechanism. {$L FASTBLIT} tells the compiler to pass FASTBLIT.OBJ to the linker. TP uses Pascal calling convention (left-to-right push, caller clears stack) and specific name mangling; assembly routines must match. A typical declaration:

{$L FASTBLIT}
procedure FastBlit(Src, Dst: pointer; Count: word); external;

The .OBJ is resolved from the current directory or object path. TASM assembles FASTBLIT.ASM with tasm /mx fastblit (case-sensitive symbols) to produce the object.

Object integration guardrails. When a unit uses {$L MODULE}, that unit must link before any unit or main program that imports it—the compiler passes OBJ references through to TLINK in use order. If MAIN uses CORE and CORE uses {$L FASTBLIT}, the linker receives CORE.OBJ (from CORE’s TPU) plus FASTBLIT.OBJ; MAIN’s OBJ comes last. A missing FASTBLIT.OBJ produces TLINK “cannot open file” or “invalid object file”—the compiler does not pre-validate {$L} references. Guardrail: run a pre-build step that checks all {$L}-referenced OBJs exist before invoking tpc. If a unit exports a procedure declared external, the OBJ must export a matching public symbol (fastblit, FASTBLIT, or whatever your assembler emits); tdump unit.obj shows the actual exports. Mismatched symbol names cause “undefined symbol” at link time. When mixing TP units with C object files, the C module must use the correct calling convention (pascal or cdecl as documented) and export names that match the Pascal external declaration; C’s default name mangling does not match TP’s expectations.

Workflow impact. Adding an external module without documenting convention leads to subtle stack corruption or wrong arguments. Pitfall: mixing TP’s default calling convention with C’s cdecl or fastcall from a C-compiled .OBJ causes unpredictable behavior. Practical check: add a BUILD_ASM.BAT that runs tasm on all .ASM files and fails if any object is missing; invoke it from the main build or document it as a prerequisite. Document the expected object-file location (ASM, SRC, or a shared OBJ lib) so new contributors know where to put compiled assembly. Part 2 goes deep on this, including object/module investigation and symbol diagnostics.

Operational checklists that saved teams

Before shipping any build profile:

clean rebuild from source (no stale artifacts)
confirm expected files (.EXE, optional .OVR, BGI assets)
compare binary size/checksum against previous known-good
run one memory-stressed boot profile test
archive build settings with artifact

This is primitive CI and still effective. A minimal pre-ship batch can automate steps 1–3:

call BUILD.BAT clean
call BUILD.BAT
if errorlevel 1 goto :eof
dir BIN\*.EXE
fc BIN\MAIN.EXE C:\RELEASE\MAIN.EXE

fc compares current build to last known-good; manual review of any diff prevents accidental regression.

Reproducibility patterns. To reproduce a build months later: (1) archive the exact BUILD.BAT, BUILD.CFG, and any CONFIG.PAS or directive files with each release; (2) record the compiler version (tpc -? output) in CHANGELOG or a BUILD_INFO.TXT; (3) avoid relying on date/time inside binaries if you need bit-identical output—some linkers embed timestamps. Clean builds from the same source with the same toolchain should produce functionally identical executables; exact byte-for-byte match may require controlling timestamp and path variables. When debugging “works on build machine, fails elsewhere,” compare the full tpc command line, PATH, and current directory between environments. A BUILD_VERBOSE.BAT that echoes %PATH%, cd, and the exact tpc invocation helps document the winning configuration.

Realistic failure modes. (a) Stale TPU: a unit was changed but an old TPU remained; symptoms include “identifier not found” at link or runtime behavior that contradicts the source. (b) Path drift: unit or object path wrong; “Cannot find unit X” or “Undefined symbol.” (c) Config mismatch: release build with debug assertions left on, or wrong overlay flags. (d) Asset missing: BGI or OVR not in expected path; InitGraph or overlay load fails at runtime. (e) Memory: loading with different TSRs or drivers changes free conventional memory; a marginal program may work in one boot and fail in another. (f) Optimization: aggressive optimization can reorder or eliminate code; a bug that disappears with {$O-} is often a race or uninitialized variable exposed by different layout. Troubleshooting patterns. For “unit version mismatch” or odd link errors: delete all .TPU and .OBJ, rebuild from scratch. Record the exact command line and paths that produced the failing build—often the fix is a path typo or missing -U rather than a source bug. For runtime path failures: add a diagnostic that prints ParamStr(0) and the path it derives for assets. For “works on my machine”: compare mem output, path, and set between machines; document minimal boot config. For crash-with-no-symbols: ensure debug build produces .MAP and that you have the exact source revision that built the crashing binary. Reproduction kit: when a user reports a crash, ask for (1) the exact EXE they ran, (2) mem and path output, (3) steps to reproduce. Rebuild from tagged source, run under TD with the same input, and use the map to set breakpoints near the fault address.

Why this part matters for the rest of the series

Parts 2 to 5 assume you understand this topology. Without it, TPU forensics, overlay policy, and BGI packaging all look like isolated tricks. They are not. They are consequences of one coherent pipeline. Part 2’s object and unit investigation relies on knowing how TPU and OBJ flow into the linker; overlay tutorials presume you manage paths and artifact placement; BGI packaging assumes asset paths and runtime resolution. A disciplined build loop and checklist habit pays off when those advanced topics introduce new failure modes. New contributors should complete the operational checklist once manually before relying on automation—the exercise builds intuition for what can go wrong and where to look when it does. Parts 3–5 (overlays, BGI, ABI) each add new artifact types and path requirements; the habits established here—clean builds, explicit paths, archived config—scale to those more complex setups.

Turbo Pascal Toolchain, Part 2: Objects, Units, and Binary Investigation

Related deep dives:

Turbo Pascal Toolchain, Part 2: Objects, Units, and Binary Investigation

Sun, 22 Feb 2026 00:00:00 +0000

Part 1 covered workflow. Part 2 goes where practical debugging starts: the actual artifacts on disk. In Turbo Pascal, build failures and runtime bugs are often solved faster by reading files and link maps than by re-reading source. The tools are simple—TDUMP, MAP files, strings, hex diffs—but used systematically they turn “it used to work” into “here is exactly what changed.”

Structure map. This article proceeds in eleven sections: (1) artifact catalog and operational meaning, (2) TP5 unit-resolution behavior, (3) TPU constraints and version coupling, (4) TPU differential forensics and reconstruction when source is missing, (5) OBJ/LIB forensics and OMF orientation, (6) MAP file workflow and TDUMP-style inspection loops, (7) EXE-level checks before deep disassembly, (8) external OBJ integration and calling-convention cautions, (9) repeatable troubleshooting matrix with high-signal checks, (10) manipulating artifacts safely and team discipline for reproducibility, and (11) unit libraries and cross references.

Artifact catalog with operational meaning

Typical TP/BP project artifacts:

.PAS: Pascal source (program or unit)
.TPU: compiled unit (compiler-consumable binary module)
.OBJ: object module (often OMF format)
.LIB: archive of .OBJ modules
.EXE/.COM: linked executable
.MAP: linker map with symbol/segment addresses
.OVR: overlay file (if overlay build path is enabled)
.BGI/.CHR: Graph unit driver/font assets

This list is not trivia. It is your debugging map. OVR files are loaded at runtime when overlay code executes; if the OVR path is wrong or the file is missing, the program may hang or crash on overlay entry rather than at startup. BGI and CHR are resolved by path at runtime—Graph unit InitGraph searches the driver path. Capture these paths in your environment documentation; “works here, fails there” often traces to BGI/OVR path differences.

Tool availability. TDUMP ships with Borland toolchains; if missing, omfdump (from the OMFutils project) or objdump with appropriate flags can suffice for OBJ/LIB inspection, though output format differs. On modern systems, strings and hexdump are standard. The workflows described here assume TDUMP is available; adapt commands if using substitutes.

Inspection tool mapping. Each artifact type has a primary inspection path: TPU → strings, hexdump, or compiler re-compile test; OBJ/LIB/EXE → TDUMP; MAP → diff against baseline. When troubleshooting, pick the artifact closest to the failure and work outward. Link failures start at OBJ/LIB; unit mismatch starts at TPU; runtime crashes may need EXE + MAP to correlate addresses with symbols.

Artifact dependency graph. A program’s build products form a directed graph: sources (.PAS, .ASM) produce TPU/OBJ; those plus linker input produce EXE; optional MAP records the link result. When a failure occurs, identify which edge of this graph is broken. “Compile works, link fails” means the TPU→EXE or OBJ→EXE edge; “link works, crash on startup” means the EXE itself or its runtime dependencies (BGI, OVR, paths). Staying aware of the graph prevents conflating compile-time and link-time issues.

Regression triage. When a previously working build starts failing, the fastest diagnostic is a binary diff: compare the new MAP and EXE (or checksums) to the last known-good. If the MAP is identical, the problem is environmental (paths, runtime, machine). If the MAP changed, the regression is in the build; then compare OBJ/TPU timestamps to see which module changed. This two-step filter—build vs environment, then which module—cuts investigation time dramatically.

TP5 unit-resolution behavior (manual-grounded)

Turbo Pascal 5.0 describes a concrete unit lookup order:

check resident units loaded from TURBO.TPL
if not resident, search <UnitName>.TPU in current directory
then search configured unit directories (/U or IDE Unit Directories)

For make/build flows that compile unit sources, <UnitName>.PAS follows the same directory search pattern.

Path-order trap. If CORE.TPU exists in both the current directory and a configured unit path, the first match wins. Two developers with different path or unit-dir settings can compile “the same” project and get different TPUs. Fix: use a single canonical unit directory and document it in BUILD.BAT or README. Resident units from TURBO.TPL bypass file search; updating a .TPU on disk has no effect if the resident copy is used. For custom units, use non-resident layout so you control the artifact.

TPU reality: powerful, version-coupled, poorly documented

.TPU is a compiled unit format designed for compiler/linker consumption, not for human readability. Two facts matter in practice:

TPUs are tightly tied to compiler version/family. TP5 TPUs are not guaranteed compatible with TP6 or BP7; even minor compiler bumps can change internal layout.
Mixing stale or cross-version TPUs causes misleading failures: “unit version mismatch,” phantom unresolved externals, or runtime corruption that does not correlate with recent edits.

Version-pinning rule: lock the compiler and RTL version for a project and do not mix TPUs built by different compilers. If migrating, rebuild all units from source under the new toolchain rather than reusing old TPUs.

Important honesty point: I cannot verify a complete, official, stable byte-level specification for late TPU variants in this repo. Practical reverse-engineering material exists, but fields and layout differ by version. So treat any fixed “TPU format diagram” from random sources as version-scoped, not universal.

TPU differential forensics (high signal technique)

When format docs are weak, compare binaries under controlled source changes.

Recommended experiment:

compile baseline unit and save U0.TPU
change implementation only, compile U1.TPU
change interface signature, compile U2.TPU
compare byte-level deltas (fc /b or hex diff tool)

Expected outcomes:

implementation-only changes affect localized regions (code blocks, constants)
interface changes tend to alter broader metadata/signature regions and may shift offsets used by dependent units

Concrete example: if you add one procedure to an interface, dependent units that uses it must be recompiled. The TPU header/symbol tables change; a stale dependent TPU can produce “unit version mismatch” or subtle ABI drift. Always keep the forensics baseline (U0.TPU) immutable; copy, don’t overwrite.

When comparing deltas, focus on regions near the start (header/metadata) versus the tail (code and data blocks). Interface changes often perturb both; pure implementation changes usually leave the header stable and alter only later regions. If a delta spans many disjoint areas, treat the unit as incompatible with prior dependents and schedule a full recompile. This gives practical understanding of compatibility sensitivity without relying on undocumented magic constants.

What to do when you only have a TPU (no source)

This is a common retro-maintenance scenario.

Step 1: classify before touching code

identify likely compiler generation (project docs, timestamps, known toolchain)
keep original TPU immutable (copy to forensics/)
confirm build environment matches expected compiler generation

Wrong compiler often produces “unit format error” or similar before any useful diagnostic. If you have multiple TP versions installed, ensure PATH and invocation point at the correct one.

Step 2: inspect for recoverable metadata

Use lightweight inspection first:

1
2

strings SOMEUNIT.TPU | less
hexdump -C SOMEUNIT.TPU | less

Expected outcome:

discover symbol-like names or error strings
estimate whether unit contains useful identifiers or is mostly opaque

If identifiers are absent, you still can treat the unit as a black-box provider.

Step 3: reconstruct interface incrementally

If you know or infer exported symbols, create a probe unit/program and compile against the TPU using conservative declarations. Iterate by compiler feedback:

declare one procedure/function candidate
compile
fix signature assumptions from diagnostics
repeat

This is slow and effective. Think of it as ABI archaeology, not decompilation.

No-source caveat. Reconstructing an interface from a TPU alone is best-effort. Some identifiers may be mangled or stripped; constant values and exact type layouts are harder to recover. When in doubt, treat the unit as opaque and call only what you can confirm compiles and behaves correctly. Do not assume undocumented TPU layout is stable across compiler versions.

Recovery priority. If you have partial source (e.g. one unit’s .PAS but not its dependencies), compile that first and see what the compiler reports as missing. The error messages often reveal needed unit or symbol names. Work from known-good declarations inward; avoid guessing large interface blocks from scratch when you can narrow the surface with compiler feedback.

Version-scoping of claims. The TPU layout and OMF record details described here are based on commonly observed behavior in TP5/BP7-era toolchains. Tool variants (TASM vs MASM, TLINK vs other linkers) can produce slightly different OBJ/LIB layouts. Where this article makes format-specific claims, treat them as applicable to the Borland toolchain family; other environments may differ.

OBJ and LIB forensics: where link truth lives

When external modules are involved, .OBJ and .LIB are usually where truth is found. In many Borland-era environments, object modules follow OMF records; you can inspect structure with TDUMP or compatible tools (e.g. omfdump, objdump with OMF support where available).

Basic inspection workflow:

1
2
3

tdump FASTBLIT.OBJ > FASTBLIT.DMP
tdump RUNTIME.LIB > RUNTIME.DMP
tdump MAIN.EXE > MAIN.DMP

For .LIB files, TDUMP lists contained object modules and their publics. For .OBJ files, you see the single module’s records. For .EXE files, you see the linked image and segment layout.

In dumps, you are looking for:

exported/public symbol names (exact spelling and decoration, if any)
unresolved externals expected from other modules
segment/class patterns that do not match expectations (e.g. CODE vs CSEG, FAR vs NEAR)

If names look right but link still fails, calling convention or far/near model mismatch is often the real issue.

Manual anchor: TP5 external declarations are linked through {$L filename}. This is documented as the assembly-language interop path for external subprogram declarations. The linker searches object directories when path is not explicit; document that search order for your setup.

OMF record-level orientation (why TDUMP output matters)

You will often see record classes such as module header (THEADR), external definitions (EXTDEF), public definitions (PUBDEF), communal definitions (COMDEF), segment definitions (SEGDEF), data records (LEDATA/LIDATA), fixups (FIXUPP), and module end (MODEND). You do not need to memorize every byte code to gain value. What matters is recognizing:

what this module exports (look for PUBDEF and similar)
what this module imports (look for EXTDEF and unresolved refs)
where relocation/fixup pressure appears (segments, frame numbers)

Example: if tdump FASTBLIT.OBJ shows a public FastCopy in segment CODE, and your Pascal declares procedure FastBlit(...) external;, the name mismatch (FastCopy vs FastBlit) will cause “unresolved external.” The dump gives you the ground truth. OMF does not standardize symbol decoration; Borland tools typically emit undecorated public names for Pascal-callable routines, whereas C compilers may prefix with underscore or use name mangling. If an OBJ came from a C build, strings on the OBJ or TDUMP’s public list shows the actual external name—use that exact form in your external declaration.

Sample TDUMP output interpretation. A typical OBJ dump might show:

Module: FASTBLIT
Segment: CODE  Align: Word  Combine: Public
  Publics: FastCopy
Externals: (none)

This tells you: the routine is named FastCopy, lives in CODE, and does not import any external symbols. If your Pascal expects FastBlit or a different segment, the mismatch is clear. For LIB dumps, you see one such block per contained OBJ; scan for the symbol you need and note which module provides it. If an OBJ lists externals, those must be satisfied by other linked modules or libraries; unresolved externals at link time usually mean a missing OBJ or LIB in the link command, or a symbol name typo in the providing module. For LIB files, link order can matter: the linker pulls in members to satisfy unresolved externals in sequence. If two OBJs in a LIB have circular references, their relative order in the archive may determine whether resolution succeeds. When adding new OBJs to a LIB, run tdump LIBNAME.LIB afterward to confirm the member list and publics; TDUMP typically does not reorder members, but some library tools do. That is enough to explain most “why does this link differently now?” questions.

Map files: the fastest way to end speculation

Generate a map file for non-trivial builds. In IDE: Options → Linker → Map file (create detailed map). On CLI: TLINK typically has a /M or similar switch for map output. Once you have a map, you can answer quickly:

did the symbol land in the expected segment?
did the expected object module get linked at all?
which module caused unexpected size growth?

MAP forensics loop:

Build with map enabled. Save GOOD.MAP as baseline.
After a change or failure, build again and compare segment/symbol layout.
If a symbol is missing or moved unexpectedly, trace back to OBJ/TPU ownership.
If total size jumps, scan the map for newly included modules or segments.

Example interpretation:

1
2
3

0001:03A0  MainLoop
0001:07C0  DrawHud
0002:0010  FastCopy   (from FASTBLIT.OBJ)

This gives direct evidence that your assembly object is linked and reachable. The 0002:0010 format is segment:offset; the (from FASTBLIT.OBJ) annotation confirms the symbol’s origin. If FastCopy does not appear, the OBJ was not linked—check {$L} and link order.

End-to-end artifact workflow example. Suppose a project fails to link with “Unresolved external FastBlit.”

Run tdump ASM\FASTBLIT.OBJ → inspect publics. If the symbol is FastCopy not FastBlit, fix the Pascal external declaration to match.
Verify {$L ASM\FASTBLIT.OBJ} is present and path correct.
Rebuild with map enabled. Check that FastCopy (or corrected name) appears in the MAP with (from FASTBLIT.OBJ).
If MAP shows the symbol but runtime crashes on call, switch to calling-convention checklist (near/far, Pascal vs cdecl, parameter order).
If all above pass, run tdump MYAPP.EXE and confirm segment layout matches expectations; then consider disassembly only as a last step.

This sequence uses TPU/OBJ/LIB/MAP/EXE in order of diagnostic payoff. Skipping to EXE or disassembly before resolving OBJ/MAP questions wastes time.

When MAP generation fails. Some minimal IDE profiles omit map output by default. If you cannot enable it, capture at least: EXE file size, list of {$L} and uses entries, and a TDUMP of the EXE for segment layout. That still beats debugging without any artifact visibility.

Checksum vs size. File size is a fast sanity check; if the EXE grows by 50KB with no new features, something changed. A simple checksum (e.g. DOS certutil or Unix cksum) catches content drift when size alone is unchanged. For release verification, checksum the EXE and key TPUs/OBJs and record them in the build log. Teams that automate this in their build script catch integration drift before it reaches users.

MAP format nuances. TLINK map files use segment:offset notation; the segment number corresponds to the link order of segments. A “detailed” map includes module origins—which OBJ or unit contributed each segment—so you can trace size bloat to a specific module. Segment class names (CODE, DATA, CSEG, DSEG) reflect compiler/linker output; minor differences across TP versions are common. When diffing MAPs, compare symbol-to-segment assignments and segment sizes rather than raw class names. A symbol that moved from one segment to another between builds can indicate model changes (e.g. near vs far) or link order tweaks.

Manipulating artifacts safely

Three levels of “manipulation” exist; do not mix them casually.

Clean rebuild manipulation: remove stale TPUs/OBJs and rebuild. Safe and repeatable. Script it: del *.TPU *.OBJ (or equivalent) before build.
Link graph manipulation: reorder/add/remove OBJ/LIB participation. Changes code layout; verify with MAP. Can expose far/near or segment ordering issues.
Binary patch manipulation: edit executable bytes post-link. Risky. Use only for experiments; document offsets, hashes, and rationale. Never treat patched binaries as release artifacts without explicit process.

Rule: if a problem appears after link-graph or binary manipulation, revert to last known-good clean build before drawing conclusions.

Clean script pattern. A minimal DOS-era clean step:

1
2
3

del *.TPU *.OBJ 2>nul
if exist BIN\*.EXE del BIN\*.EXE
if exist BIN\*.MAP del BIN\*.MAP

Run this before any “full rebuild” or when chasing artifact-related bugs. Keep source (.PAS, .ASM) and build scripts; treat everything else as regenerable.

Unit libraries and TPUMOVER note

Some TP/BP installations include tooling such as TPUMOVER for packaging unit modules into library containers. Availability and exact workflows are installation-dependent. If present, treat library generation as a release artifact with version pinning, not as a casual local convenience. Migrating TPUs between library and loose-file form can alter search order; document which layout the project uses.

Libraries vs loose TPUs. Loose TPUs in a directory are easier to individually inspect, checksum, and replace during development. Library (TUM-style) packaging reduces file count and can speed unit search on slow media. Choose one approach per project and stick with it; mixing both for the same units invites “which version did we actually link?” confusion.

TPUMOVER and library maintenance. When you add or remove units from a library, always rebuild the library from a clean state rather than incrementally patching. Stale or partially updated libraries produce the same mystery failures as stale TPUs. After any library change, run a full clean rebuild of the main program and verify the MAP reflects the expected unit set. Treat the library as an intermediate build product, not a hand-edited asset.

External OBJ integration: robust declaration pattern

Pascal side:

{$L FASTBLIT.OBJ}
procedure FastBlit(var Dst; const Src; Count: Word); external;

Expected outcome before first run:

link succeeds with no unresolved external
call does not corrupt stack
output buffer changes exactly as test vector predicts

If link succeeds but behavior is wrong, suspect ABI mismatch first. Before blaming the algorithm, verify parameter alignment: Turbo Pascal typically aligns parameters to word boundaries; an assembly routine expecting byte-precise layout may read garbage. Return-value handling also varies: functions returning Word or Integer use AX; LongInt uses DX:AX; records and strings use hidden pointer parameters. Document what your external returns and how the caller expects it; mismatches cause wrong values, not link errors.

Calling-convention cautions. Turbo Pascal’s default calling convention (typically near, Pascal-style: left-to-right push, caller cleans stack) must match the external routine. Common failure modes:

C vs Pascal convention: C pushes right-to-left and often uses different name decoration. If the OBJ came from C (TCC, BCC), declare with cdecl or equivalent where the compiler supports it.
Near vs far: {$F+} forces far calls; assembly routines must use RET FAR and matching prolog. Mismatch causes return to wrong address.
Parameter order and types: var passes pointer; const can pass pointer or value depending on size. Word-sized Count must match assembly expectations (byte, word, or dword).
Segment assumptions: If the OBJ assumes a particular DS or ES setup, document it. Pascal does not guarantee segment registers at call boundary.

Document every external in a small header comment: source file, compiler/TASM options used, calling convention, and any non-default assumptions.

Integration test pattern. Before relying on an external in production code, add a minimal harness that calls it with known inputs and verifies output. For example, fill two buffers, call the routine, and assert the result. If that passes, the OBJ is correctly integrated; failures point to convention or parameter mismatches before you bury the call in complex logic. Run it immediately after linking.

TP5 reference also states {$L filename} is a local directive and searches object directories when a path is not explicit, which is a common source of machine-to-machine drift. Prefer explicit paths in build scripts: {$L ASM\FASTBLIT.OBJ}.

TLIB workflow for multi-module assembly. When you have several .ASM files producing .OBJ modules, you can either list each with {$L mod1.OBJ} {$L mod2.OBJ} … or build a .LIB and link that. TLIB creates/updates libraries:

`1`	`tlib FASTMATH +FASTBLIT +FASTMUL +FASTDIV`

Then {$L FASTMATH.LIB} pulls in all modules. TDUMP on the LIB shows which modules and publics it contains. Use a LIB when you have many OBJ files and want a single linkable unit; keep OBJ references when you need explicit control over link order (e.g. for overlays or segment placement).

EXE-level checks before disassembly

Before deep reversing, inspect executable-level metadata. TDUMP on .EXE shows DOS header, relocation table, segment layout, and entry point. The DOS header contains the relocation count (number of fixups applied at load), initial CS:IP (entry point), and initial SS:SP (stack). Relocation entries point to segment references that the loader patches when loading at a non-default base; a change in relocation count often indicates new far pointers or segment-relative refs.

High-signal EXE checks:

relocation count changes (indicates new segments or far model shifts)
stack/code entry metadata drift
total image size deltas
segment order and class names (e.g. CODE, DATA, STACK)

`1`	`tdump MYAPP.EXE \| findstr /i "reloc entry segment"`

Or capture full dump and diff against known-good:

1
2

tdump MYAPP.EXE > MYAPP_EXE.DMP
fc /b MYAPP_EXE.DMP BASELINE_EXE.DMP

Large unexpected changes usually indicate build-profile or link-graph drift, not random compiler mood. This quick check avoids hours of aimless debugging. If the EXE header and relocation table match a known-good build, but behavior differs, the problem is likely runtime (paths, overlays, memory) rather than link-time.

High-value troubleshooting table

Use this as a repeatable decision matrix. Check in order; do not skip to disassembly before ruling out high-signal causes. The goal is to eliminate most failures with minimal tool use—TDUMP, MAP diff, and clean rebuild cover the majority of cases.

“Unresolved external”

Most likely causes (check first):

symbol spelling/case mismatch (TDUMP the OBJ for exact public name)
missing object or library in link graph (verify {$L} and TLINK command)
module compiled for incompatible object format/profile (OMF vs COFF, etc.)
wrong unit or OBJ pulled from alternate path (path order, current dir)

Quick check: tdump SYMBOL.OBJ | findstr /i "public pubdef" — does the exported name match your Pascal external declaration exactly?

“Runs, then random crash after external call”

Most likely causes (check first):

parameter passing mismatch (order, size, var vs value)
caller/callee stack cleanup mismatch (Pascal vs cdecl)
near/far routine mismatch (return address on wrong stack location)
segment register assumptions violated (DS, ES not as assembly expects)

Quick check: Add a minimal passthrough test: call the routine with known-good inputs and confirm output. If that works, the failure is in integration, not the routine itself.

“Unit version mismatch”

Most likely causes:

TPU built by different compiler version
interface changed but dependent unit not recompiled
stale TPU in a path that shadows the correct one

Quick check: Delete all TPUs, rebuild from scratch. If it works, you had stale artifacts.

“Binary suddenly huge”

Most likely causes:

profile drift (debug info/checks enabled)
broad library dependency pull
accidental static inclusion of assets/modules (BGI linked in, large data)

Quick check: Compare MAP files. New segments or modules explain the growth.

“Works on my machine, fails elsewhere”

Most likely causes:

path differences (unit dir, object dir, BGI dir, overlay dir)
different DOS/TSR footprint (less conventional memory)
different compiler or RTL version installed

Quick check: Document paths and versions on working machine; replicate exactly on failing one, or ship with explicit relative paths.

“Overlay load fails or hangs”

Most likely causes:

OVR file not in working directory or configured overlay path
overlay unit compiled with different memory model than main program
overlay segment size exceeds OVR file (truncated or mismatched build)

Quick check: Confirm OVR file size matches expectations; run tdump on the EXE to see overlay segment declarations. Compare with a known-good overlay build.

Summary: signal order for artifact inspection

When you do not know where to start, use this priority:

MAP — fastest way to see what actually linked. Generate it; diff it.
OBJ/LIB + TDUMP — resolves “unresolved external” and symbol-name issues.
TPU — resolves “unit version mismatch” and interface drift; use differential forensics when format is unknown.
EXE + TDUMP — confirms final layout; use when MAP and OBJ checks pass but runtime behavior is wrong.
Disassembly — last resort when binary layout is correct but logic is suspect.

Most TP toolchain bugs are solved at steps 1–3. Avoid jumping to 4–5 without evidence.

Checkpoint discipline. When you have a working build, immediately: (a) save BASELINE.MAP, (b) note EXE size and optionally CRC, (c) archive BUILD.TXT. If a later change breaks things, you can diff MAP vs baseline, compare sizes, and often pinpoint the regression without touching source. Teams that skip checkpoints repeat the same forensic work repeatedly. A single baseline from a known-good build can save hours of regression hunting.

Before seeking help. If you are stuck and plan to ask a colleague or post online, gather: exact error message, compiler/linker version, output of tdump on the failing OBJ (for link errors) or EXE (for runtime), and a one-line description of the last change. That context turns “it doesn’t work” into a solvable puzzle. Omitting the MAP or TDUMP output is the most common reason diagnostic threads go nowhere.

A disciplined binary investigation loop

state expected outcome before run
build clean (no stale TPU/OBJ)
capture .EXE size/hash + .MAP
inspect changed symbols/segments first
only then debug/disassemble

This order keeps you from chasing folklore. Teams that skip step 3 often waste hours on “it used to work” bugs that are pure link/artifact drift.

When the loop stalls. If you have done clean rebuild, MAP diff, TDUMP on OBJ and EXE, and the problem persists, the cause may be environmental: TSR conflicts, EMS/XMS driver behavior, or DOS version differences. At that point narrow the environment: boot minimal config, disable TSRs, try a different DOS version or machine. Document the minimal repro configuration; that becomes the bug report. Before concluding “environment only,” re-run the loop with a single-source-change variation: revert the most recent edit, rebuild, and compare. If the revert fixes it, the regression is in that change, not the environment—even when the artifact diff is subtle.

Team and process discipline for artifact reproducibility

Reproducibility fails when one developer has hidden state that others do not. Enforce these practices:

Version-lock the toolchain: document exact TP/BP version, TASM version, and any third-party units. Rebuild from source on a clean checkout must produce identical artifacts.
Explicit paths in scripts: avoid “current directory” assumptions. Build scripts should set PATH, unit dirs, and object dirs explicitly.
Archive build products with releases: keep EXE + MAP + optional OVR and a short BUILD.TXT (compiler version, options, date) in the release package. That gives future maintainers a diff target.
One clean rebuild before any “weird bug” investigation: if a bug appears after days of incremental builds, delete TPUs/OBJs and rebuild. Many “impossible” bugs vanish.
ABI checkpoint for externals: when integrating a new OBJ, record its public symbols (from TDUMP), calling convention, and any segment or alignment assumptions in a small integration doc. Future maintainers can verify correctness without re-deriving the ABI from scratch.
Treat TPU/OBJ as derived, never committed: only source (.PAS, .ASM) goes in version control. Rebuild artifact sets from source on each machine. Committed TPUs from one developer’s machine can silently break another’s build when compiler versions differ. Document this policy in the project README.

These rules are low-cost and eliminate a large class of non-reproducible failures.

Build log discipline. For each release or debugging baseline, record in BUILD.TXT or equivalent: compiler executable and version, key options ({$D+}, {$R+}, memory model), unit and object paths, and checksum or size of the main EXE. When a bug report arrives months later, that log tells you whether you can reproduce the exact binary or must narrow the search.

Handoff protocol. When passing a project to another maintainer, include: source tree, BUILD.BAT or equivalent, BASELINE.MAP from last known-good build, and a one-page “toolchain and paths” document. Without that, the next person spends days rediscovering unit search order, object paths, and which TP version was used. The hour you spend documenting pays off on the first “works on my machine” incident.

Cross references

Next part

Part 3 moves from artifacts to runtime memory strategy: overlays, near/far costs, and link strategy under hard 640K pressure.

Turbo Pascal Toolchain, Part 3: Overlays, Memory Models, and Link Strategy

Summary for busy maintainers. When a TP project misbehaves: (1) clean rebuild first; (2) generate and diff the MAP; (3) TDUMP any external OBJs to confirm symbol names; (4) verify calling conventions on externals; (5) check path and version consistency. Most failures resolve before you touch a disassembler. Treat TPU/OBJ as version-locked, path-explicit, and never-committed. Document once; benefit forever. The artifact-focused mindset that Part 1 introduced becomes concrete here: files on disk are your primary evidence, source code is secondary when debugging build and link failures.

Turbo Pascal Toolchain, Part 3: Overlays, Memory Models, and Link Strategy

Sun, 22 Feb 2026 00:00:00 +0000

This article is rewritten to be explicitly source-grounded against the Turbo Pascal 5.0 Reference Guide (1989), Chapter 13 (“Overlays”) plus Appendix B directive entries.

Structure map. 1) Why overlays existed—mechanism, DOS memory pressure, design tradeoffs. 2) TP5 hard rules and directive semantics. 3) FAR/near call model and memory implications. 4) Build and link strategy for overlaid programs. 5) Runtime initialization: OvrInit, OvrInitEMS, OvrSetBuf usage and diagnostics. 6) Overlay buffer economics and memory budget math. 7) Failure triage and performance profiling mindset. 8) Migration from non-overlay projects. 9) Engineering checklist and boundary caveats.

Version note. This article is grounded in the TP5 Reference Guide. Borland Pascal 7 and later overlay implementations may differ in details (e.g. EMS handling, buffer API). The core rules—{$O+}, FAR chain, compile-to-disk, init-before-use—tend to hold across versions, but when in doubt, consult the manual for your specific toolchain. TP6/TP7 improvements are beyond the scope of this piece; the TP5 baseline remains the most widely documented and forms a stable reference.

Why overlays existed

In TP5 real-mode DOS workflows, overlays are a memory-management strategy: keep non-hot code out of always-resident memory and load it on demand. Conventional memory in DOS is capped at roughly 640 KB; TSRs, drivers, and stack/heap shrink the usable space. A large application can easily exceed that budget if all code is resident.

Mechanism. The overlay manager maintains a buffer in conventional memory. Overlaid routines live in a separate .OVR file on disk. On first call into an overlaid routine, the manager loads the appropriate block into the buffer and transfers control. Subsequent calls to already-loaded overlays execute in-place; no disk access. When the buffer fills and a new overlay must load, the manager discards inactive overlays first (least-recently-used policy), then loads the requested block.

Constraints. The buffer must hold at least the largest overlay (including fix-up data). Overlay call-path constraints matter: cross-calling overlay clusters—routines in overlay A calling routines in overlay B—force repeated swaps if the buffer is too small. Design the call graph so overlay entry points are used in bursts; avoid ping-pong patterns (A→B→A→B) where each transition evicts the previous overlay. Cold code that runs infrequently benefits most; hot paths that recur in tight loops should stay resident. A report generator that runs once per session is an ideal overlay candidate; a validation routine called on every keystroke is not.

Failure modes. Undersized buffer: visible thrashing, multi-hundred-millisecond stalls on each swap. Missing .OVR at runtime: init fails, calling overlaid code yields error 208. Incorrect FAR-call chain: corruption or crash when control returns through a near-call frame.

Design tradeoffs. Overlays reduce resident footprint at the cost of latency on first use and complexity in build and deployment. They help when (a) total code size exceeds available conventional memory, or (b) resident footprint must shrink to coexist with TSRs or other programs. They hurt when cold code is called frequently in alternation—e.g. A→B→A→B—because each transition may force a reload. Packaging and deployment hazards: the .OVR file must deploy alongside the .EXE with a matching base name. ZIP extracts that place .EXE in one folder and .OVR in another, or installers that omit the .OVR, produce ovrNotFound at startup. Document in release notes that both files must stay together; test packaging on a clean directory.

TP5 hard rules (not optional style)

For TP5 overlaid programs, these are the baseline rules:

Overlaid units must be compiled with {$O+}.
At any call to an overlaid routine in another module, all active routines in the current call chain must use FAR call model.
Use {$O unitname} in the program (after uses) to select overlaid units.
uses must list Overlay before overlaid units.
Programs with overlaid units must compile to disk (not memory).

TP5 also states that among the listed standard units only Dos is overlayable; System, Overlay, Crt, Graph, Turbo3, and Graph3 are not.

Tuning workflow. Before enabling overlays, identify cold units (e.g. report generators, rarely-used wizards) and compile them with {$O+}. Add {$O unitname} one unit at a time and rebuild; verify .OVR appears and size changes as expected. Link-map triage: with -Fm (or equivalent map-file option) the linker produces a .MAP file. Overlaid segments appear in a dedicated overlay region; resident segments stay in the main program listing. If you add {$O UnitName} but the map shows that unit’s code still in the main program, the directive did not take effect—often due to placement after uses or a compile-to-memory build. If link fails or .OVR is missing, the overlay selection is not taking effect—check directive placement and uses order.

Failure when rules are violated. Omitting {$O+} on an overlaid unit: compiler error. Omitting {$F+} on a caller in the chain: link may succeed but runtime can corrupt. Forgetting uses Overlay before overlaid units: the Overlay unit’s runtime is not linked; overlay manager never initializes. Compiling to memory: overlay linker path is bypassed; no .OVR produced.

What `{$O+}` actually changes

{$O+} is not just a marker. TP5 documents concrete codegen precautions: when calls cross units compiled with {$O+} and string/set constants are passed, the compiler copies code-segment-based constants into stack temporaries before passing pointers. This prevents invalid pointers if overlay swaps replace caller unit code areas.

That detail is the reason “works in tiny test, crashes in integrated flow” happens when overlay directives are inconsistent.

Mechanism. Without {$O+}, a call like DoReport('Monthly') may pass a pointer to a constant in the code segment. If DoReport is overlaid and triggers a swap, the caller’s code segment can be evicted; the pointer then points at overlay buffer contents, not the original string. With {$O+}, the compiler emits logic to copy the constant to the stack and pass that address instead.

Constraint. {$O unitname} has no effect inside a unit—it is a program-level directive. The unit must already be compiled with {$O+} or the compiler reports an error. Mixing {$O+} and {$O-} inconsistently across a call chain is a common source of intermittent corruption. The same rule applies to sets passed by reference: set constants in the code segment can become invalid if the caller is evicted during an overlay swap. TP5 copies both strings and sets into stack temporaries when the callee may be overlaid.

Example of the constant-copy hazard. In a unit compiled without {$O+}, WriteReport(HeaderText) might pass the address of HeaderText as stored in the code segment. If WriteReport is overlaid and triggers a swap, the caller’s code may be evicted; the callee then reads from wrong memory. With {$O+}, the compiler generates a copy to a stack temporary and passes that address—safe regardless of overlay activity.

FAR-call requirement explained operationally

Manual example pattern: MainC -> MainB -> OvrA where OvrA is in an overlaid unit. At call to OvrA, both MainB and MainC are active, so they must use FAR model too.

Practical TP5-safe strategy:

{$O+,F+} in overlaid units
{$F+} in main program and other units

TP5 notes the cost is usually limited: one extra stack word per active routine and one extra byte per call.

FAR vs near implications. Near calls use a 2-byte return address (offset only); FAR calls use 4 bytes (segment:offset). Each active frame on the stack therefore costs one extra word (2 bytes) with {$F+}. For deeply nested call chains—e.g. main → menu → dialog → validator → report—the stack growth is 2 * depth bytes. In a 64 KB stack, that is rarely the bottleneck; the overlay buffer and heap compete more for conventional memory.

Memory budget math. A rough breakdown for a typical overlaid TP5 app:

DOS + drivers + TSRs: ~100–200 KB (varies)
Resident code (main, Crt, Graph init, hot units): ~80–150 KB
Overlay buffer (OvrSetBuf): 32–64 KB typical, up to MemAvail + OvrGetBuf
Heap ({$M min,max}): remaining conventional memory
Stack: usually 16–32 KB

If MemAvail at startup is small, increasing overlay buffer via OvrSetBuf reduces heap. Tune with MemAvail and OvrGetBuf diagnostics before and after OvrSetBuf. Runtime initialization variants: OvrSetBuf must run while the heap is empty. Two common orderings: (a) OvrInit → OvrSetBuf → heap consumers (Graph, etc.); or (b) OvrInit only, accepting the default buffer. If your program uses Graph, call OvrSetBuf before InitGraph—the Graph unit allocates large video and font buffers from the heap, which locks in the overlay buffer size. Late OvrSetBuf after any heap allocation has no effect; no runtime error, but the buffer stays at its initial minimum.

Segment implications. In real-mode 8086, a FAR call pushes segment and offset; a near call pushes only offset. When resident code calls overlay code, control crosses segment boundaries. The overlay buffer lives in a different segment than the main code segment. A near return in the caller would pop only 2 bytes—the offset—and jump back with a stale segment, typically causing an immediate crash or wild jump. FAR ensures the full return address is preserved. This is why the rule applies to the entire call chain, not just the immediate caller.

Build and selection flow (TP5)

Minimal structure:

program App;
{$F+}
uses Overlay, Dos, MyColdUnit, MyHotUnit;
{$O MyColdUnit}

Key nuances:

{$O unitname} has no effect inside a unit.
It only selects used program units for placement in .OVR.
Unit must already be compiled in {$O+} state or compiler errors.

Build/link strategy. Overlays are a link-time feature. The pipeline:

Compile each unit to .TPU (with correct {$O+} for overlaid units).
Compile the main program; the compiler records overlay directives.
Link produces .EXE and .OVR. The linker segregates code marked for overlay into the .OVR file and emits call stubs in the .EXE.

A minimal batch build for an overlaid project:

@echo off
rem Overlaid build: units first, then main, linker produces EXE+OVR
tpc -B MyColdUnit.pas
tpc -B MyHotUnit.pas
tpc -B Main.pas
if errorlevel 1 goto fail
if not exist Main.OVR echo WARNING: No .OVR produced - overlay selection may be inactive
goto ok
:fail
echo Build failed
exit /b 1
:ok
echo Main.EXE + Main.OVR ready

Checklist. After a clean build: (1) .EXE and .OVR exist; (2) .OVR size roughly matches sum of overlaid unit contributions; (3) running without .OVR fails explicitly at init, not later with corruption; (4) if using external .OBJ modules that participate in overlay call chains, ensure they use FAR call/return conventions compatible with TP’s expectations; (5) for release builds, confirm both artifacts are present in the output directory and in any packaging script—CI or automated build pipelines that copy only .EXE will ship a broken product.

IDE vs CLI parity. Overlay options in the IDE (Compiler → Overlay unit names, Memory compilation off) must match what a batch build does. If the IDE build produces .OVR but the CLI build does not, the IDE may have overlay settings that are not reflected in project files. Document the exact options and replicate them in the batch script.

Using .MAP for overlay forensics. With link map output enabled (e.g. tpc -Fm or IDE Linker → Map file), the map file shows segment addresses and symbol placement. Overlaid segments appear in the overlay region; resident segments in the main program. Link-map-based triage: (1) Compare map before and after adding {$O unitname}—overlaid units should move from main-program segments into the overlay section. (2) If a unit’s code remains in the main program despite {$O unitname}, the directive was ignored (check placement, compile-to-disk, uses order). (3) Use segment sizes in the map to estimate .OVR size and the minimum OvrSetBuf; the largest overlay block sets the floor. Comparing map before and after adding {$O unitname} confirms which code moved to the overlay file.

Runtime initialization contract

Overlay manager must be initialized before first overlaid call:

OvrInit('APP.OVR');
if OvrResult <> ovrOk then Halt(1);

If initialization fails and you still call overlaid code, TP5 behavior is runtime error 208 (“Overlay manager not installed”).

`OvrInit` behavior (TP5)

Opens/initializes overlay file.
If filename has no path, search includes current directory, EXE directory (DOS 3.x), and PATH.
Typical errors: ovrError, ovrNotFound.

`OvrInitEMS` behavior (TP5)

Attempts to load overlay file into EMS.
On success, subsequent loads become in-memory transfers from EMS to the overlay buffer—faster than disk, but overlays still execute from conventional memory. EMS acts as a paging store, not execution space.
On error, manager keeps functioning with disk-backed overlay loading.

EMS usage pattern. Call OvrInit first, then OvrInitEMS. If OvrResult is ovrOk after OvrInitEMS, the manager uses EMS for overlay storage. On ovrNoEMSDriver or ovrNoEMSMemory, the program continues with disk loading; no need to fail. EMS reduces load latency on machines with expanded memory but is optional for correctness. EMS tradeoffs: EMS removes disk I/O from overlay loads—a floppy or slow hard disk can add 100–500 ms per swap; EMS cuts that to a few milliseconds. The tradeoff is memory pressure: the full .OVR is duplicated in EMS. On a machine with limited EMS (e.g. 256 KB), loading a 120 KB overlay file may exhaust EMS and force fallback to disk anyway. Check OvrResult after OvrInitEMS; if it is ovrNoEMSMemory, consider reducing overlay count or advising users with low EMS to free expanded memory. On machines without EMS, OvrInitEMS returns ovrNoEMSDriver and the program silently continues with disk—no special handling required.

`OvrResult` semantics

Unlike IOResult, TP5 documents that OvrResult is not auto-cleared when read. You can inspect it directly without first copying.

Usage patterns and diagnostics

Pattern 1: minimal init with explicit path. Avoid search-order surprises by building the overlay path from the executable location:

procedure InitOverlays;
var ExeDir, ExeName, ExeExt: PathStr;
begin
  FSplit(ParamStr(0), ExeDir, ExeName, ExeExt);
  OvrInit(ExeDir + ExeName + '.OVR');
  if OvrResult <> ovrOk then
  begin
    case OvrResult of
      ovrError:   WriteLn('Overlay format error or program has no overlays');
      ovrNotFound: WriteLn('Overlay file not found: ', ExeDir + ExeName + '.OVR');
      else       WriteLn('OvrResult=', OvrResult);
    end;
    Halt(1);
  end;
end;

Pattern 2: EMS-optional with fallback. Try EMS first; if it fails, disk loading still works:

OvrInit(ExeDir + ExeName + '.OVR');
if OvrResult <> ovrOk then Halt(1);
OvrInitEMS;  { ignore result: disk loading remains available }

Pattern 3: buffer tuning before heap allocation. Call OvrSetBuf while the heap is empty. With Graph unit:

OvrInit(OvrFile);
if OvrResult <> ovrOk then Halt(1);
OvrSetBuf(50000);   { before InitGraph }
InitGraph(...);     { Graph allocates from heap }

OvrResult reference (TP5 manual-confirmed): ovrOk, ovrError, ovrNotFound, ovrIOError, ovrNoEMSDriver, ovrNoEMSMemory.

OvrSetBuf diagnostics. The call can fail if the heap is not empty or BufSize is out of range. TP5 does not document a dedicated OvrResult for OvrSetBuf failure; practical approach: call OvrSetBuf(DesiredSize) early, then check OvrGetBuf to see if the buffer actually increased. If OvrGetBuf stays at the initial size, the request was rejected (heap in use or size constraint). Add a diagnostic mode that prints MemAvail, OvrGetBuf, and MaxAvail at startup to support troubleshooting.

Initialization ordering variants. Three common patterns: (a) Minimal: OvrInit(path) only, accept default buffer—works when overlays are small and rarely cross-call. (b) Buffer-tuned: OvrInit → OvrSetBuf(n) before any heap use—required when Graph or other heap consumers follow. (c) EMS-aware: OvrInit → OvrInitEMS → OvrSetBuf—EMS can speed loads, but OvrSetBuf still controls conventional-memory buffer size. In all cases, init must complete before the first overlaid call; unit initializations that invoke overlaid code will fail with error 208.

How the Overlay unit lays out memory (brief)

TP5 splits resident and overlaid code at artifact level:

.EXE: resident (non-overlaid) program parts
.OVR: overlaid units selected by {$O unitname}

At runtime, overlaid code executes from a dedicated overlay buffer in conventional memory. Manual-confirmed points:

initial buffer size is the smallest workable value: the largest overlay (including fix-up information)
OvrSetBuf changes buffer size by taking/releasing heap space
OvrSetBuf requires an empty heap to take effect
manager tries to keep as many overlays resident as possible and discards inactive overlays first when space is needed
with EMS (OvrInitEMS), overlays are still copied into normal memory buffer before execution

Linker behavior (manual-confirmed). The TP5 overlay linker produces one .OVR per executable. All units marked with {$O unitname} contribute code to that file. The linker decides the layout; you do not control which routines share overlay blocks. Unused routines in overlaid units may be omitted (dead-code elimination). The .OVR is loaded as a whole or in logical chunks depending on the manager implementation—TP5 docs do not specify the exact block structure, but the runtime behavior (LRU discard, buffer sizing) is documented. When sizing the overlay buffer, use the largest single overlay block; the linker may pack multiple small routines into one loadable block, so OvrGetBuf after init reflects the runtime’s minimum—the size of the largest block the manager must load in one swap.

FAR/near and overlay placement. Overlaid code runs in a separate buffer; the linker emits FAR calls to reach it from resident code. Resident routines that call overlaid routines must use FAR so the return address correctly restores the caller’s segment. Near calls in that chain would leave a truncated return address and corrupt the stack. The constraint applies to the entire active call chain at the moment of the overlaid call: main → menu → dialog → validator → report. If report is overlaid, every routine in that path must use FAR. A single near caller in the chain—e.g. a quick helper compiled with {$F-}—can cause intermittent crashes when control returns through that frame; the stack ends up with a mismatched segment.

Buffer economics: `OvrGetBuf` and `OvrSetBuf`

TP5 starts with a minimal buffer sized to the largest overlay (including fix-up data). For cross-calling overlay clusters, this can thrash badly.

OvrSetBuf tunes buffer size, with constraints:

BufSize must be >= initial size
BufSize must be <= MemAvail + OvrGetBuf
heap must be empty, otherwise call returns error/has no effect

Important ordering rule: if Graph is used, call OvrSetBuf before InitGraph because Graph allocates heap memory.

Tuning workflow. (1) At startup, log MemAvail and OvrGetBuf before any OvrSetBuf. (2) Run a representative workload (menu navigation, report run, etc.) and note perceived stalls. (3) Increase buffer in steps (e.g. 16K → 32K → 48K → 64K) and re-test. (4) Stop when stalls disappear or MemAvail drops unsafely. (5) Adjust {$M min,max} if the larger buffer causes heap shortage during normal operation.

Practical overlay tuning checklist:

Step	Action	Success criteria
1	`OvrGetBuf` after init	Know baseline buffer size
2	Run cold-path sequence 3×	Count noticeable pauses
3	`OvrSetBuf(2 * OvrGetBuf)`	Fewer pauses
4	Iterate until smooth or `MemAvail` < 20K	Balanced

Concrete sizing examples. If the largest overlay is 24 KB, the initial buffer is ~24 KB. With two overlays that cross-call (e.g. Report → Chart), a 24 KB buffer forces a swap on every transition. OvrSetBuf(48000) holds both; transitions become in-memory. If MemAvail at startup is 120 KB, reserving 48 KB for overlays leaves ~72 KB for heap—adequate for many apps. If MemAvail is 40 KB, a 48 KB buffer request may fail or leave almost no heap; tune down or reduce resident code.

Buffer and Graph/BGI interaction. The Graph unit allocates video buffers, font caches, and driver data from the heap at InitGraph time. If you call OvrSetBuf after InitGraph, the heap is no longer empty; the call has no effect and the buffer stays at its initial size. Always initialize overlays and set buffer size before any substantial heap allocation. Order: OvrInit → OvrSetBuf → InitGraph (or other heap consumers). See Part 4: BGI integration for graphics-specific overlay notes.

Failure triage and performance profiling mindset

Symptom → check → fix:

Link error / unresolved overlay symbol: Unit not in overlay selection, or mixed far/near in external .OBJ. Verify {$O unitname} and {$F+} on all units in the call chain.
Error 208 at runtime: Overlay manager not installed. Either OvrInit was never called, or it failed and execution continued. Add init check before any overlaid call.
ovrNotFound at startup: Path wrong. Use FSplit(ParamStr(0), ...) to build overlay path from EXE location; avoid relying on current directory.
ovrError at startup: .OVR does not match .EXE (rebuilt one but not the other), or program has no overlays. Clean rebuild both, verify .OVR exists.
Intermittent slowdown / visible stalls: Buffer thrashing. Profile by repeating the slow action and measuring; increase OvrSetBuf or move hot helpers to resident units. Cross-reference with the link map: if the buffer is smaller than the sum of frequently-used overlay block sizes, thrashing is expected. Increase buffer until it holds the active set, or consolidate overlays to reduce cross-calling.

Performance profiling mindset. Overlay cost is load time, not execution time. A loaded overlay runs at full speed. Latency profiling workflow: (1) isolate the user action that triggers the stall; (2) wrap the suspect call in GetTime/GetMsCount timing; (3) run the action multiple times—first call (cold) vs later calls (warm); (4) if cold is 100+ ms and warm is under 5 ms, the stall is overlay load; (5) trace the call path to see which overlaid units participate; (6) either enlarge buffer (to hold multiple overlays) or move frequently-alternating code to resident units. Simple timing around suspect calls (GetTime before/after) confirms whether the stall aligns with overlay load. Minimal diagnostic snippet:

var Hour, Min, Sec, Sec100: Word;
    StartTotal, EndTotal: LongInt;
begin
  GetTime(Hour, Min, Sec, Sec100);
  StartTotal := LongInt(Sec)*100 + Sec100;
  RunSuspectedOverlaidRoutine;
  GetTime(Hour, Min, Sec, Sec100);
  EndTotal := LongInt(Sec)*100 + Sec100;
  WriteLn('Elapsed: ', EndTotal - StartTotal, ' centiseconds');
end;

If the first call shows hundreds of centiseconds and later calls are near zero, the overlay load is the bottleneck. Disk-based loads on a 360K floppy can reach 500 ms or more; EMS typically drops that to under 20 ms. Use this to correlate user-reported “slow menu” complaints with overlay activity.

LRU behavior in practice. The overlay manager keeps the most recently used overlays in the buffer. Alternating rapidly between overlay A and overlay B with a buffer that holds only one forces a load on every switch. Holding both in buffer (or reducing cross-calls) eliminates that cost. Profile the actual call sequence during representative use; if the user typically runs Report then Chart then Report again, a buffer large enough for both pays off.

Migration from non-overlay projects

Converting a working non-overlaid program to use overlays:

Identify cold units. Report generators, rarely-used dialogs, optional modules. Do not overlay hot loops (main menu, render loop, I/O). Practical heuristic: if a routine runs on every frame or in a tight loop, keep it resident. If it runs only when the user selects a specific menu item or triggers an infrequent action, it is a cold-path candidate. Use profiler or manual instrumentation if unsure.
Add {$O+} and {$F+} to candidate units. Add {$F+} to main program and any unit that calls overlaid code (directly or transitively).
Add uses Overlay as first unit in the main program. Add {$O UnitName}
for each cold unit, one at a time.
Enable compile-to-disk if building in IDE (Options → Compiler → Directories or equivalent).
Add init block before first overlaid call. Use FSplit + OvrInit + OvrResult check.
Clean rebuild. Verify .EXE and .OVR both produced. Run missing-OVR test. Run overlay-thrash test and tune OvrSetBuf.
Regression test the full feature set. Overlays change memory layout; subtle bugs (e.g. uninitialized pointers, stack overflow) can surface.

Rollback: Remove uses Overlay, {$O unitname}, and {$O+} from overlaid units; reduce {$F+} if no longer needed. Rebuild; .OVR will not be produced, all code returns to .EXE.

Incremental migration. Do not overlay everything at once. Start with one clearly cold unit. Validate build, init, and runtime. Add a second; re-validate. If a new overlay causes problems, the failure is localized to that unit or its callers. Batch migration makes triage much harder.

Common migration pitfalls. (a) Overlaying a unit that is used by many others—transitive callers all need {$F+}. (b) Forgetting {$O+} on one unit in a cluster—inconsistent codegen can cause pointer corruption. (c) Deploying .EXE without .OVR—build and packaging scripts must include both. (d) Calling overlaid code before OvrInit—e.g. from unit initialization sections—crashes; init must run in the main program before any overlaid routine is invoked. (e) Packaging hazards: self-extracting archives that copy only .EXE files, installers with file filters that exclude .OVR, or ZIP-based distributions where users extract to different folders—all produce ovrNotFound. Include both files in every distribution artifact; add a post-install check that verifies EXE_dir + base_name + '.OVR' exists, or document clearly that the program requires both files in the same directory.

What is manual-confirmed vs inferred

Manual-confirmed in TP5:

directive rules ($O+, $O unitname, $F+ guidance)
compile-to-disk requirement
runtime API behavior (OvrInit, OvrInitEMS, OvrSetBuf, OvrResult)
FAR-chain safety requirement and consequences

Intentionally not claimed here as fixed TP5 public spec:

detailed byte-level .OVR file format guarantees
universal behavior across TP6/TP7/BP7 variants without version checks

Those may be explored, but should be treated as version-scoped reverse engineering.

Engineering checklist

Before shipping an overlaid TP5 build:

verify overlaid units compiled with {$O+}
verify FAR-call policy ({$F+} strategy) across active-call paths
verify {$O unitname} directives and uses Overlay ordering
verify .EXE and .OVR artifact pair in package
run one missing-OVR startup test and confirm controlled failure path
run one overlay-thrash workload and tune with OvrSetBuf
log MemAvail and OvrGetBuf at startup for support diagnostics
document OvrSetBuf value and {$M} in build notes
include .OVR in installer and distribution package; document that .EXE and .OVR must stay together

Deployment note. End users rarely see .OVR files. Installer scripts and ZIP distributions must include both .EXE and .OVR with matching base names. A self-extracting archive or installer that only grabs the .EXE will produce a program that fails at startup with ovrNotFound. Packaging/deployment hazards: (1) Build scripts that copy *.EXE but not *.OVR into a release directory. (2) Version-control or backup systems that ignore *.OVR by default. (3) Users running from a network drive where the .OVR lives on a different path than the .EXE. (4) Multi-directory installs (e.g. EXE in \bin, OVR in \data) without updating the overlay search path—OvrInit with no path uses current directory and EXE directory; explicit path construction via ParamStr(0) avoids ambiguity. Add a pre-release checklist item: verify both artifacts exist in the shipped package.

Turbo Pascal Toolchain, Part 5: From 6.0 to 7.0 - Compiler, Linker, and Language Growth

Sun, 22 Feb 2026 00:00:00 +0000

Parts 1-4 covered workflow, artifacts, overlays, and BGI integration. This last part goes inside the compiler/language boundary: memory assumptions, type layout, calling conventions, and assembler integration from TP6-era practice to TP7/BP7 scope.

Structure map

Version framing — TP6 vs TP7/BP7 scope, continuity and deltas
Execution model — real-mode assumptions, segmentation, near/far
Data type layout — size table, alignment, layout probe harness
Memory layout consequences — ShortString, sets, records, arrays
Procedures vs functions — semantics and ABI implications
Calling conventions — stack layout, parameter order, return strategy
Compiler directives — policy, safety controls, project-wide usage
Assembler integration — inline blocks, external OBJ, boundary contracts
TP6→TP7 migration — pipeline evolution, artifact implications, language growth
Protected mode and OOP — BP7 context, object layout, VMT considerations
Migration checklist — risk controls, test loops, regression traps, common pitfalls

Version framing: what changed and what stayed stable

The TP6 to TP7 shift was less a language revolution and more an expansion of operational surface:

larger project/tooling workflows became easier
artifact and mixed-language integration became more central
language core stayed recognizably Turbo Pascal

So the technical model below is largely continuous across this generation, with feature breadth increasing in later packaging. Borland Pascal 7 (BP7) extended this further with protected-mode compilation, built-in debugging support, and richer IDE integration, while TP7 remained primarily a real-mode product.

Version-specific nuances — TP7.0 (1990) stabilized the TP6 object model and improved unit compilation speed. TP7.1 addressed bugs and refinements; some teams held at 7.0 for compatibility with shared codebases. BP7 (1992) bundled Turbo Debugger, expanded the RTL, and introduced DPMI target support. Exact behavior of directives like {$G+} (80286 instructions), {$A+} (record alignment), and codegen choices can vary between these builds; when precise version behavior matters, treat claims here as a starting point and validate against your toolchain.

Execution model assumptions (the non-negotiables)

Real-mode DOS assumptions drive everything:

Segmented memory model — 64 KB segments, selector:offset addressing, 20-bit physical address space. DS usually points at the program’s data; SS at the stack; CS at code. Overlays swap code segments in and out of a single overlay area.
16-bit register-centric calling paths — AX, BX, CX, DX, SI, DI, BP, SP; segment registers CS, DS, SS, ES.
Near vs far distinctions — near calls use same segment (16-bit offset), far calls require segment:offset (32-bit); overlay units demand far entry points.
Conventional memory pressure — first 640 KB shared by DOS, TSRs, drivers, and your program; overlays and heap compete for the same pool.

The linker’s choice of memory model (Tiny, Small, Medium, Large, Huge) constrains code and data segment layout. TP6 and TP7 both default to Small model in typical configurations: one code segment, one data segment, with near pointers. Tiny folds code and data into one segment (for .COM output); Medium allows multiple code segments (far code, near data); Large/Huge allow multiple data segments with far pointers—changing pointer size from 2 to 4 bytes. Switching to Large model changes pointer sizes and call conventions; map-file analysis becomes essential when hunting link errors or unexpected runtime behavior.

Artifact implications — Small model yields a single .EXE with code and data in separate segments. Overlays add .OVR files; each overlay is its own code segment loaded on demand. The linker produces a .MAP file listing segment addresses and public symbols; use it to verify overlay boundaries and diagnose “fixup overflow” or segment-order issues. Segment order in the map (CODE, DATA, overlay segments) affects load addresses; changing unit compile order can shift symbols and break code that assumes fixed offsets. A typical map lists segments in load order with start/stop addresses; overlays appear as named segments with their size—verify overlay sizes match expectations before debugging load failures.

Data layout and ABI — Record fields, set bit layouts, and string formats are stable within a compiler version but can differ across TP6, TP7, and BP7. When sharing binary structures (e.g., files or shared memory) between programs built with different toolchains, define a canonical layout and validate with layout probes. Ignoring these constraints while reading Pascal source leads to wrong performance and ABI conclusions. A layout-probe program that prints SizeOf for all shared types, run under each toolchain, gives a quick compatibility report before committing to a cross-toolchain design.

Data type layout: practical table

Common TP-era sizes in real-mode profiles:

Byte: 1 byte
ShortInt: 1 byte
Word: 2 bytes
Integer: 2 bytes
LongInt: 4 bytes
Char: 1 byte
Boolean: 1 byte
Pointer: 4 bytes (segment:offset in real mode)
String[N]: N+1 bytes (length byte + payload)

Floating-point and extended numeric types (Real, Single, Double, Extended, Comp) exist with version/profile-specific behavior and FPU/emulation settings, so treat exact codegen cost as configuration dependent. With {$N+}, the compiler uses native FPU instructions; with {$N-}, software emulation (via runtime library) is typical. Real is typically 6-byte BCD in older profiles and can map to Single or a software type in others—verify in your build. Extended is 10 bytes (80-bit); Comp is 8-byte integer format often used for currency. Set types use one bit per element; set of 0..7 is 1 byte, set of 0..15 is 2 bytes, up to 32 bytes for set of 0..255.

Alignment and packing — Turbo Pascal generally packs record fields without inserting padding; fields align to their natural size (1, 2, 4 bytes). The {$A+/-} (Align Records) directive, where available, can change this—{$A+} may align record fields to word boundaries for faster access on some processors. Packed records (packed record) minimize size at potential performance cost. For structures crossing the Pascal–C–assembly boundary, explicit layout verification is mandatory; C struct alignment rules often differ.

Quick layout probe harness

If binary layout matters, measure your exact compiler profile:

program LayoutProbe;
type
  TRec = record
    B: Byte;
    W: Word;
    L: LongInt;
  end;
  TPackedRec = packed record
    B: Byte;
    W: Word;
  end;
begin
  Writeln('SizeOf(Integer)=', SizeOf(Integer));
  Writeln('SizeOf(Pointer)=', SizeOf(Pointer));
  Writeln('SizeOf(String[20])=', SizeOf(String[20]));
  Writeln('SizeOf(TRec)=', SizeOf(TRec));
  Writeln('SizeOf(TPackedRec)=', SizeOf(TPackedRec));
  Writeln('SizeOf(Single)=', SizeOf(Single), ' SizeOf(Real)=', SizeOf(Real));
end.

Expected outcome: concrete numbers for your environment. Never assume layout from memory when ABI compatibility is at stake.

Memory layout consequences developers felt daily

ShortString behavior

String in classic Turbo Pascal is a short string (length-prefixed), not a null-terminated C string. Consequences:

O(1) length read via byte 0
max 255 characters; String[80] is 81 bytes
direct interop with C APIs needs conversion: either build a null-terminated copy or pass Str[1] and ensure the C side respects the length byte

A simple conversion helper for C library calls (TP7’s Strings unit has StrPCopy; this illustrates the manual pattern):

procedure PascalToCString(const S: String; var Buf; MaxLen: Byte);
var
  I: Byte;
  P: ^Char;
begin
  P := @Buf;
  I := 0;
  while (I < S[0]) and (I < MaxLen - 1) do begin
    P^ := S[I + 1];
    Inc(P); Inc(I);
  end;
  P^ := #0;
end;

Set and record layout

Set/record memory footprint is compact but sensitive to declared ranges and packing decisions. A set of 0..255 consumes up to 32 bytes (one bit per element); smaller ranges use fewer bytes (e.g., set of 0..15 is 2 bytes). Record alignment follows the directive and packing mode. Bit ordering within set bytes is implementation-defined; when exchanging set values with C or assembly, document and test the mapping. If binary compatibility matters, verify layout with SizeOf tests in a dedicated compatibility harness. TP6 and TP7 generally match on these layouts, but mixed toolchains (e.g., C object modules) may introduce padding differences.

Arrays

Arrays are contiguous. High-throughput code benefits from locality, but segment boundaries and index range checks (if enabled) influence speed and safety. Multi-dimensional arrays are stored in row-major order. Static arrays and open-array parameters have different calling semantics: open arrays pass a hidden length (typically as the last parameter or in a known slot), which affects the ABI at procedure boundaries. Example:

procedure Process(const Arr: array of Integer);  { Arr: ptr + hidden High(Len) }

String parameters pass by reference (address of the length byte); value parameters of record type may be copied onto the stack or via a hidden pointer, depending on size—records larger than a few bytes often use a hidden var parameter to avoid stack bloat. When interfacing with assembly, document how each parameter type is passed.

Procedures vs functions: not just syntax

Difference in language semantics:

procedure: action with no return value
function: returns value and can appear in expressions

Difference in engineering use:

procedures often model side-effecting operations
functions often model value computation or query paths

In low-level interop, function return strategy and calling convention details matter for ABI compatibility with external objects. Scalars (Byte, Word, Integer, LongInt, pointers) typically return in registers: Byte in AL, Word/Integer in AX, LongInt in DX:AX (high word in DX, low in AX), pointers in DX:AX (segment in DX, offset in AX). Larger types (records, arrays) may use a hidden var parameter or a caller-allocated temporary; the threshold and mechanism vary by version and type size—commonly, records exceeding 4 bytes use a hidden first parameter for the return buffer.

When calling or implementing assembly routines that mimic Pascal functions, match the return mechanism or corruption is likely. A function declared external in Pascal must place its return value where the Pascal caller expects it; an inline asm block that computes a LongInt return should leave the result in DX:AX before the block ends. For Word returns, ensure the high byte of AX is clean if the caller extends the value.

Calling conventions and ABI boundaries

Turbo Pascal default calling convention differs from C conventions commonly used by external modules. Pascal uses left-to-right parameter push order; C typically uses right-to-left (cdecl). Pascal procedures usually clean the stack (ret N); C callers often clean (cdecl). Name mangling can differ: Pascal may export symbols with no decoration or with a leading underscore; C compilers vary. At integration boundaries, define explicitly:

Parameter order — left-to-right (Pascal) vs right-to-left (C)
Stack cleanup responsibility — callee (Pascal-style) vs caller (cdecl)
Near vs far procedure model — must match declaration and link unit
Value return mechanism — register vs stack for large returns

If any of these is ambiguous, “link succeeds but runtime breaks” is predictable.

Stack frame layout — The compiler sets up BP as a frame pointer; parameters are accessed via positive offsets from BP. For a near call, the return address occupies 2 bytes (IP only); for a far call, 4 bytes (CS:IP). Parameter offsets shift accordingly. Typical Pascal caller view: parameters pushed left-to-right, then call. Callee sees highest parameter at lowest address. Example frame for Proc(A: Word; B: LongInt) (near call):

{ Stack grows down. After PUSH BP; MOV BP, SP: BP+2 = ret addr, BP+4 = first param }
{ BP+4 = A (Word), BP+6 = B low, BP+8 = B high. Callee uses RET 6. }
{ For far call: BP+4 = CS, BP+6 = IP; first param at BP+8. }

Near procedures use CALL near ptr and RET; far procedures use CALL far ptr and RETF. The callee must not change BP, SP, or segment registers except as permitted by the convention. For external C routines, use cdecl or equivalent where the object was built with C; otherwise stack imbalance or wrong parameter binding occurs. Inline assembly that calls external code must replicate the expected convention:

function CStrLen(P: PChar): Word; cdecl; external 'CLIB';
// or, if linking C OBJ directly:
{$L mystr.obj}
function CStrLen(P: PChar): Word; cdecl; external;

In mixed-language projects, write one tiny ABI verification test per external routine family before integrating into real logic—e.g., call with known inputs, assert expected output. Example harness: a small program that calls MulAcc(100, 200, 50), expects a known result, and exits with code 0 on success; run it immediately after linking a new assembly module to catch offset or cleanup mismatches before they surface in production.

Compiler directives as architecture controls

Directives are not cosmetic. They change behavior and generated code.

Examples frequently used in serious projects:

{$R+/-}: range checking — array bounds, subrange
{$Q+/-}: overflow checking — integer arithmetic
{$S+/-}: stack checking — overflow sentinel
{$I+/-}: I/O checking — handle errors vs continue
{$G+/-}: 80286+ instructions (in BP7/profile-dependent builds)
{$N+/-} and related: FPU vs software float

Exact availability/effects vary by version/profile, so freeze directive policy per build profile and avoid per-file drift. A project-wide policy file or leading include can enforce consistency:

{ GLOBAL.INC - lock directives for release build }
{$R+}  { Range check in debug only if you prefer; some teams use {$R-} for ship }
{$Q-}  { Overflow off for speed in release }
{$S+}  { Stack overflow detection recommended }
{$I+}  { I/O errors as exceptions or Check(IOResult) }
{$F+}  { FAR calls if using overlays }

TP5/TP6/TP7 anchor points:

{$F+/-} (Force FAR Calls) is a local directive with default {$F-}.
In {$F-} state, compiler chooses FAR for interface-declared unit routines and NEAR otherwise.
Overlay-heavy programs are advised to use {$F+} broadly to satisfy overlay FAR-call requirements.

For {$DEFINE} and conditional compilation, centralize symbols (e.g., DEBUG, USE_OVERLAYS) so builds stay reproducible. Avoid scattering version-specific {$IFDEF} blocks without documentation. Use {$IFOPT R+} to check directive state rather than relying on a separate define when debugging build configuration.

Directive gotchas — {$R+} adds runtime cost; many shipped builds use {$R-}. {$I+} makes I/O failures raise runtime errors; {$I-} requires explicit IOResult checks. Switching these mid-project causes subtle bugs. Directive scope matters: a unit’s directives do not always affect the main program unless inherited via include. Document the chosen directive set in a README or build script so new contributors do not override them.

Assembler integration paths

Turbo Pascal projects typically used two integration patterns:

Inline assembler blocks inside Pascal source — asm ... end
External object modules linked with {$L filename.OBJ} declarations

Inline path is great for small hot routines where Pascal symbol visibility helps; you can reference parameters and locals by name. External path is better for larger modules and reuse across projects. Both require strict stack discipline and adherence to the chosen calling convention. Inline blocks cannot use RET or RETF to exit the routine—control must flow to the block end so the compiler can emit the standard epilogue. For conditional exit, use goto to a label after the block or restructure the logic.

Inline assembler

Minimal inline shape:

function BiosTicks: LongInt;
begin
  asm
    mov ah, $00
    int $1A
    mov word ptr [BiosTicks], dx
    mov word ptr [BiosTicks+2], cx
  end;
end;

This style keeps the function contract in Pascal while performing low-level work in assembly. It is ideal for small hardware-touching routines. The compiler generates prologue/epilogue; your inline block must preserve BP, SP, and segment registers as required. Do not assume register contents on entry except parameters passed in. DS and SS are typically valid for data/stack access; ES may be used for string operations or be undefined—save and restore if you modify it.

External OBJ integration

{$L FASTMATH.OBJ}
function MulAcc(A, B, C: Word): Word; external;

The OBJ must export a public symbol matching the Pascal identifier. Calling convention (parameter order, stack cleanup, near/far) must match. If the OBJ was built with TASM or MASM, ensure the PROC declaration uses the right model (e.g., NEAR/FAR) and that parameter offsets line up with Pascal’s push order. Example TASM side for function MulAcc(A, B, C: Word): Word:

.MODEL small
.CODE
PUBLIC MulAcc
MulAcc PROC
  push bp
  mov  bp, sp
  mov  ax, [bp+4]   ; A
  mov  bx, [bp+6]   ; B
  mov  cx, [bp+8]   ; C
  ; ... compute result in AX ...
  pop  bp
  ret  6
MulAcc ENDP
END

Pascal passes A, B, C left-to-right (A at lowest offset); callee cleans with RET 6. Mismatch in offset or cleanup causes wrong results or stack crash. Note: BP+4 assumes a 2-byte return address for near calls; far calls use 4 bytes, so offsets shift—for the same routine declared far, A would be at BP+8. Always verify against the generated Pascal code or map file. A quick sanity check: compile a trivial Pascal wrapper that calls the external routine with known values, run it, and assert the result before integrating into production.

Boundary contract checklist

Before relying on an external routine:

symbol resolves at link (no “undefined external” or mangling mismatch)
stack discipline preserved (balanced push/pop, correct ret form)
deterministic output under vector tests

If the third condition fails, ABI mismatch is the first suspect. Add a minimal harness that calls the routine with known inputs and asserts the result before integrating into production code. Record the test in the project so future linker or compiler upgrades can re-validate. Mixed Pascal–C–assembly projects benefit from a single “ABI smoke” program that exercises every external boundary with canned inputs.

TP6→TP7 migration: pipeline evolution and artifact implications

Compiler and linker pipeline

From TP6 to TP7, the pipeline stayed conceptually the same: compile units to OBJ, link OBJ with RTL and any external modules to EXE. The flow is: source (.PAS) → compiler (TPC.EXE / TPCX.EXE) → object (.OBJ) → linker (TLINK.EXE) → executable (.EXE) and optional map (.MAP). Overlay units add an extra overlay manager and .OVR files produced during linking. Command-line builds typically use TPC with options for target model and overlays; the IDE invokes the same tools under the hood. Saving OBJ files from each compile allows incremental linking and faster iteration, but migration should start from a full clean rebuild.

Behavioral shifts — TP7’s compiler produced more consistent symbol naming and improved handling of large unit graphs. The linker remained TLINK; its /m, /s, and overlay options work similarly across TP6 and TP7, but segment ordering and fixup resolution can produce different map layouts. When comparing before/after migration, expect segment addresses to change even when logic is identical.

What changed was robustness and integration:

Larger projects — TP7 handled more units and larger dependency graphs without tripping over internal limits. Map file output and symbol resolution improved.
Object file compatibility — TP6 OBJs generally link with TP7, but the reverse is not guaranteed; TP7 may emit slightly different record layouts or name mangling in edge cases. Recompile from source when migrating, do not mix TP6 and TP7 object files.
RTL and units — Standard units (Crt, Dos, Graph, etc.) evolved; some routines gained parameters or changed behavior. Re-test code that relies on unit internals. Graph unit BGI handling, Dos unit path parsing, and Crt screen buffer assumptions are frequent sources of minor incompatibility.
OBJ linkage — TP7’s TLink (or TLINK) remained compatible with TASM/MASM object format. Mixed Pascal–assembly projects typically compile Pascal to OBJ, assemble .ASM to OBJ, then link together. Ensure segment naming and model (SMALL, MEDIUM, etc.) match across all modules. Use PUBLIC and EXTRN in assembly to mirror Pascal’s external declarations; symbol names must match exactly. A “Fixup overflow” or “Segment alignment” error often indicates model or segment-name mismatch between modules.

Language and OOP growth

TP6 introduced objects; TP7 refined them. Object layout (VMT, instance size) generally remained compatible, but virtual method tables and constructor/destructor semantics can vary. BP7 added further extensions. For migration:

Recompile all object-based units under TP7.
Run targeted tests on inheritance chains and virtual overrides.
Avoid depending on undocumented VMT layout.

Objects store the VMT pointer at a fixed offset (often the first field); virtual methods are dispatched through it. When writing assembly that allocates or manipulates object instances, preserve that layout:

type
  TBase = object
    X: Integer;
    procedure DoSomething; virtual;
  end;
  PBase = ^TBase;

Instance size and VMT offset are compiler-dependent; use SizeOf(TBase) and avoid hardcoding. Constructor calls initialize the VMT pointer; manual allocation (e.g., New or heap blocks) requires proper init. Descendant objects add their fields after the parent’s; single inheritance keeps layout predictable. Multiple inheritance was not part of classic Turbo Pascal objects, so no VMT merging concerns apply. When passing object instances to assembly, pass the pointer (^TBase) and treat the first word/dword as the VMT pointer.

Constructor and destructor order — Turbo Pascal objects use Constructor Init and Destructor Done (or custom names). Call order matters: base constructors before derived, destructors in reverse. Failing to call the destructor on heap-allocated objects leaks memory. TP7 tightened some edge cases around constructor chaining; if migration reveals odd behavior in object init, compare TP6 and TP7 object code for the constructor to spot differences.

Protected mode and BP7 context

Borland Pascal 7 added protected-mode compilation, producing DPMI-compatible executables that can access extended memory. Key implications:

Segment model — 32-bit selectors instead of 16-bit segments; pointer representation and segment arithmetic differ. Code that assumes real-mode segment:offset layout may fail. Far pointers in protected mode are selector:offset but the selector is a DPMI descriptor, not a physical segment. Near pointers remain 32-bit offsets within a segment; the segment limit is 4 GB in 32-bit mode, changing allocation and pointer-arithmetic assumptions.
RTL differences — Protected-mode RTL uses DPMI calls for memory and interrupts; DOS file I/O and system calls go through the DPMI host. Heap allocation, overlay loading, and BGI driver loading all route differently than in real mode.
Assembly interop — Inline and external assembly must use 32-bit-safe patterns; some real-mode tricks (segment manipulation, direct ports) require different handling. Real-mode int instructions work via DPMI emulation but with different semantics for protected-mode interrupts.

OOP in protected mode — Object and VMT layout are compatible with real-mode BP7, but instance allocation and constructor behavior may differ when the RTL uses DPMI memory services. Virtual method dispatch itself is unchanged; problems typically arise from code that reads segment values or assumes physical addresses. If your project stays in real mode, TP7 is sufficient. Moving to BP7 protected mode is a larger migration: treat it as a separate phase with dedicated tests. Real-mode TP7 binaries remain the norm for DOS-targeted applications; BP7 protected-mode targets DPMI-aware environments (e.g., Windows 3.x, OS/2, or standalone DPMI hosts like 386MAX).

Practical migration checklist (technical, not nostalgic)

1) Freeze known-good TP6 artifacts and checksums.
2) Rebuild clean under target TP7/BP7 environment.
3) Compare executable and map deltas.
4) Re-validate external OBJ ABI assumptions.
5) Re-test overlays + graphics + TSR-heavy runtime profile.
6) Lock directives/options into documented profile files.

Each step is auditable: (1) gives a baseline; (2) isolates toolchain change; (3) surfaces size and symbol shifts; (4) catches OBJ/ABI drift; (5) exercises integration points; (6) prevents future drift from stray directive changes. Run the checklist in order; skipping (1) or (2) makes later steps harder to interpret when regressions appear.

Risk controls

Baseline capture — Checksum the TP6 EXE and map before migration; record build date and compiler version. Store baseline outputs in a known location; diff tools and checksum utilities should be available for comparison.
Incremental migration — Migrate one unit or subsystem at a time where possible; isolate changes to reduce debugging scope. Migrate leaf units (those with no dependencies on other project units) first; then work inward toward the main program.
Fallback — Keep TP6 build environment available until TP7 build is validated. If TP7 regression appears, you can bisect by reverting units. Preserve TP6 compiler, linker, and RTL paths; document them so the fallback is reproducible.

Test loops

Smoke — Program starts, minimal user path completes. Include at least one path that loads overlays and one that uses BGI if the project employs them; silent failure on init is common.
Regression traps — Known inputs that produced known outputs under TP6; re-run and compare under TP7. Capture checksums or golden files for critical outputs (reports, exports, screenshots). Automate where possible: a batch script that runs the program with canned input and diffs output against baseline catches many regressions.
Boundary tests — Overlay load/unload, BGI init/close, TSR hooks, assembly entry points. Exercise code paths that touch segmented memory or far pointers. Add a dedicated test that calls every external assembly routine with edge values (0, -1, max) to uncover ABI mismatches.

Expected outcome

Same behavior with clarified build policy, or
Explicit, measurable deltas you can explain and document.

Not acceptable: “it feels mostly fine” without verification. Aim for a migration report that states: baseline version, target version, checksum deltas (or “identical”), test results (pass/fail counts), and any known behavioral differences with root cause. Future maintainers will thank you.

Common migration pitfalls

Mixed OBJ versions — Linking TP6 units with TP7-built units can produce subtle ABI mismatches. Clean rebuild from source.
Directive inheritance — Unit A’s directives can affect units that use it; a stray {$R-} in a deeply included file can disable range checks project-wide.
Overlay entry points — Overlays require far calls; if {$F-} is set where overlay code is invoked, near calls hit the wrong segment and crash.
BGI driver paths — TP7 may look for .BGI files in different locations; verify InitGraph and driver loading.
FPU detection — {$N+} assumes FPU present; on 8086/8088, use {$N-} or runtime detection to avoid invalid opcode traps.
Map file drift — After migration, diff the new map against the baseline. Segment order and symbol addresses may shift; large or unexpected changes warrant investigation. If overlay segment names or orders change, overlay load addresses will differ—ensure overlay manager configuration matches the new map.

Where this series goes next

You asked for practical depth, so this series now has dedicated companion labs:

Full series index

If you want the next layer, I recommend one additional article focused only on calling-convention lab work with map-file-backed stack tracing across Pascal and assembly boundaries.

Toolchain on TurboVision

Turbo Pascal Toolchain, Part 6: Object Pascal, TPW, and the Windows Transition

Structure map (balanced chapter plan)

Object Pascal arrives: TP 5.5 and the OOP extensions

Turbo Pascal for Windows 1.0: the first wave

TPW 1.5 and the post-TP7 landscape

BP7: unified DOS and Windows toolchain

OWL and message-driven architecture

Technical culprits and pitfalls

Debugging workflows: DOS vs Windows

Build and deploy: DOS vs Windows

Team collaboration and mental model shift

Synthesis: what the toolchain taught

Practical migration: DOS to Windows checklist

Related reading

Full series index

Turbo Pascal Toolchain, Part 7: From TPW to Delphi and the RAD Mindset

Structure map (balanced chapter plan)

Historical grounding: 1993–1996

What was at stake: from resource wrangler to form designer

Form and resource workflow changes

The object inspector and design-time behavior

The component model and packages

Third-party components and the ecosystem

Culprits and pitfalls during migration

Build and release workflow

Testing and debugging mentality shift

Architecture implications

Delivery model and team process changes

Practical migration patterns

First 90-day Delphi adoption cadence

Summary and outlook

Related reading

Turbo Pascal History Through Tooling Decisions

Why that era felt so productive

Distribution shaped engineering choices

Unit system as collaboration contract

Build behavior and trust

Debugging as craft, not ceremony

What modern teams can still steal

Tooling history as systems history

Practical way to study it now

Turbo Pascal Toolchain, Part 1: Anatomy and Workflow

Scope and version boundaries

Toolchain topology (what talks to what)

Artifact pipeline as engineering signal

IDE settings are architecture settings

Directory and path policy (where projects fail first)

Practical project shape

IDE and CLI parity is non-negotiable

Units are compile boundaries, not just reuse

Debug loop mechanics

External objects from day one

Operational checklists that saved teams

Why this part matters for the rest of the series

Turbo Pascal Toolchain, Part 2: Objects, Units, and Binary Investigation

Artifact catalog with operational meaning

TP5 unit-resolution behavior (manual-grounded)

TPU reality: powerful, version-coupled, poorly documented

TPU differential forensics (high signal technique)

What to do when you only have a TPU (no source)

Step 1: classify before touching code

Step 2: inspect for recoverable metadata

Step 3: reconstruct interface incrementally

OBJ and LIB forensics: where link truth lives

OMF record-level orientation (why TDUMP output matters)

Map files: the fastest way to end speculation

Manipulating artifacts safely

Unit libraries and TPUMOVER note

External OBJ integration: robust declaration pattern

EXE-level checks before disassembly

High-value troubleshooting table

“Unresolved external”

“Runs, then random crash after external call”

“Unit version mismatch”

“Binary suddenly huge”

“Works on my machine, fails elsewhere”

“Overlay load fails or hangs”

Summary: signal order for artifact inspection

A disciplined binary investigation loop

What `{$O+}` actually changes

`OvrInit` behavior (TP5)

`OvrInitEMS` behavior (TP5)

`OvrResult` semantics

Buffer economics: `OvrGetBuf` and `OvrSetBuf`