Dos 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.

Deterministic DIR Output as an Operational Contract

Tue, 10 Mar 2026 00:00:00 +0000

The story starts at 23:14 in a room with two beige towers, one half-dead fluorescent tube, and a whiteboard covered in hand-written file counts. We had one mission: rebuild a damaged release set from mixed backup disks and compare it against a known-good manifest.

On paper, that sounds easy. In practice, it meant parsing DIR output across different machines, each configured slightly differently, each with enough personality to make automation fail at the worst moment.

By 23:42 we had already hit the first trap. One machine produced DIR output that looked “normal” to a human and ambiguous to a parser. Another printed dates in a different shape. A third had enough local customization that every assumption broke after line three. We were not failing because DOS was bad. We were failing because we had not written down what “correct output” meant.

That night we stopped treating DIR as a casual command and started treating it as an API contract.

This article is that deep dive: why a deterministic profile matters, how to structure it, and how to parse it without superstitions.

The turning point: formatting is behavior

In modern systems, people accept that JSON schemas and protocol contracts are architecture. In DOS-era workflows, plain text command output played that same role. If your automation consumed command output, formatting was behavior.

Our internal profile locked one specific command shape:

DIR [drive:][path][filespec]
default long listing
no /W, no /B, no formatting switches
fixed US date/time rendering (MM-DD-YY, h:mma / h:mmp)

That scoping decision solved half the problem. We stopped pretending one parser should support every possible switch/locale and instead declared a strict operating envelope.

A canonical listing is worth hours of debugging

The profile included a canonical example and we used it as a fixture:

 Volume in drive C has no label
 Volume Serial Number is 3F2A-19C0

 Directory of C:\RETROLAB

AUTOEXEC BAT      1024 03-09-96  9:40a
BIN              <DIR> 03-08-96  4:15p
DOCS             <DIR> 03-07-96 11:02a
README   TXT       512 03-09-96 10:20a
SRC              <DIR> 03-07-96 11:04a
TOOLS    EXE     49152 03-09-96 10:21a
       3 File(s)      50,688 bytes
       3 Dir(s)  14,327,808 bytes free

Why include this in a spec? Because examples settle debates that prose cannot. When two engineers disagree, the fixture wins.

The 38-column row discipline

The core entry template was fixed-width:

`1`	`%-8s %-3s %8s %8s %6s`

That yields exactly 38 columns:

columns 1..8: basename (left-aligned)
column 9: space
columns 10..12: extension (left-aligned)
columns 13..14: spaces
columns 15..22: size-or-dir (right-aligned)
column 23: space
columns 24..31: date
column 32: space
columns 33..38: time (right-aligned)

Once you adopt positional parsing instead of regex guesswork, DIR lines become boring in the best way.

Why this works even on noisy nights

Fixed-width parsing has practical advantages under pressure:

no locale-sensitive token splitting for date/time columns
no ambiguity between <DIR> and size values
deterministic handling of one-digit vs two-digit hour
easy visual validation during manual triage

At 01:12, when you are diffing listings by eye and caffeine alone, “column 15 starts the size field” is operational mercy.

Header and footer are part of the protocol

Many parsers only parse entry rows and ignore header/footer. That is a missed opportunity.

Our profile explicitly fixed header sequence:

volume label line (is <LABEL> or has no label)
serial line (XXXX-XXXX, uppercase hex)
blank line
Directory of <PATH>
blank line

And footer sequence:

file totals: %8u File(s) %11s bytes
dir/free totals: %8u Dir(s) %11s bytes free

Those two footer lines are not decoration. They are integrity checks. If parsed file count says 127 and footer says 126, stop and investigate before touching production disks.

Parsing algorithm we actually trusted

This is the skeleton we converged on in Turbo Pascal style:

type
  TDirEntry = record
    BaseName: string[8];
    Ext: string[3];
    IsDir: Boolean;
    SizeBytes: LongInt;
    DateText: string[8]; { MM-DD-YY }
    TimeText: string[6]; { right-aligned h:mma/h:mmp }
  end;

function TrimRight(const S: string): string;
var
  I: Integer;
begin
  I := Length(S);
  while (I > 0) and (S[I] = ' ') do Dec(I);
  TrimRight := Copy(S, 1, I);
end;

function ParseEntryLine(const L: string; var E: TDirEntry): Boolean;
var
  NameField, ExtField, SizeField, DateField, TimeField: string;
  Code: Integer;
begin
  ParseEntryLine := False;
  if Length(L) < 38 then Exit;

  NameField := Copy(L, 1, 8);
  ExtField  := Copy(L, 10, 3);
  SizeField := Copy(L, 15, 8);
  DateField := Copy(L, 24, 8);
  TimeField := Copy(L, 33, 6);

  E.BaseName := TrimRight(NameField);
  E.Ext      := TrimRight(ExtField);
  E.DateText := DateField;
  E.TimeText := TimeField;

  if TrimRight(SizeField) = '<DIR>' then
  begin
    E.IsDir := True;
    E.SizeBytes := 0;
  end
  else
  begin
    E.IsDir := False;
    Val(TrimRight(SizeField), E.SizeBytes, Code);
    if Code <> 0 then Exit;
  end;

  ParseEntryLine := True;
end;

This parser is intentionally plain. No hidden assumptions, no dynamic heuristics, no “best effort.” It either matches the profile or fails loudly.

Edge cases that must be explicit

The spec was strict about awkward but common cases:

extensionless files: extension field is blank (three spaces in raw row)
short names/exts: right-padding in fixed fields
directories always use <DIR> in size field
if value exceeds width, allow rightward overflow; never truncate data

The overflow rule is subtle and important. Truncation creates false data, and false data is worse than ugly formatting.

Counting bytes: grouped vs ungrouped is not random

A detail teams often forget:

entry SIZE_OR_DIR file size is decimal without grouping
footer byte totals are grouped with US commas in this profile

That split looks cosmetic until a parser accidentally strips commas in one place but not the other. If totals are part of your acceptance gate, normalize once and test it with fixtures.

The fictional incident that made it real

At 02:07 in our story, we finally had a clean parse on machine A. We ran the same process on machine B, then compared manifests. Everything looked perfect except one tiny mismatch: file count agreed, byte count differed by 1,024.

Old us would have guessed corruption and started copying disks again.

Spec-driven us inspected footer math first, then entry parse, then source listing capture. The issue was not corruption. One listing had accidentally included a generated staging file from a side directory because the operator typed a wildcard path incorrectly.

The deterministic header (Directory of ...) and footer checks caught it in minutes.

No drama. Just protocol discipline.

What this teaches beyond DOS

The strongest lesson is not “DOS output is neat.” The lesson is operational:

any text output consumed by tools should be treated as a contract
contracts need explicit scope and out-of-scope declarations
examples + field widths + sequence rules beat vague descriptions
integrity lines (counts/totals) should be first-class validation points

That mindset scales from floppy-era rebuild scripts to modern CI logs and telemetry processors.

Implementation checklist for your own parser

If you want a stable implementation from this profile:

enforce command profile (no unsupported switches)
parse header in strict order
parse entry rows by fixed columns, not token split
parse footer totals and cross-check with computed values
fail explicitly on profile deviation
keep canonical fixture listings in version control

This gives you deterministic behavior and debuggable failures.

Closing scene

At 03:18 we printed two manifests, one from recovered media and one from archive baseline, and compared them line by line. For the first time that night, we trusted the result.

Not because the room got quieter.
Not because the disks got newer.
Because the contract got clearer.

The old DOS prompt did what old prompts always do: it reflected our discipline back at us.

Related reading:

VFAT to 8.3: The Shortname Rules Behind the Curtain

Tue, 10 Mar 2026 00:00:00 +0000

The second story begins with a floppy label that looked harmless:

RELEASE_NOTES_FINAL_REALLY_FINAL.TXT

By itself, that filename is only mildly annoying. Inside a mixed DOS/Windows pipeline in 1990s tooling, it can become a release blocker.

Our fictional team learned this in one long weekend. The packager ran on a VFAT-capable machine. The installer verifier ran in a strict DOS context. The build ledger expected 8.3 aliases. Nobody had documented the shortname translation rules completely. Everybody thought they “basically knew” them.

“Basically” lasted until the audit script flagged twelve mismatches that were all technically valid and operationally catastrophic.

This article is the deep dive we wish we had then: how long names become 8.3 aliases, how collisions are resolved, and how to build deterministic tooling around those rules.

First principle: translate per path component

The most important rule is easy to miss:

Translation happens per single path component, not on the full path string.

That means each directory name and final file name is handled independently. If you normalize the entire path in one pass, you will eventually generate aliases that cannot exist in real directory contexts.

In practical terms:

C:\SRC\Very Long Directory\My Program Source.pas
is translated component-by-component, each with its own collision scope

That “collision scope” phrase matters. Uniqueness is enforced within a directory, not globally across the volume.

Fast path: already legal 8.3 names stay as-is

If the input is already a legal short name after OEM uppercase normalization, use that 8.3 form directly (uppercase).

This avoids unnecessary alias churn and preserves operator expectations. A file named CONFIG.SYS should not become something novel just because your algorithm always builds FIRST6~1.

Teams that skip this rule create avoidable incompatibilities.

When alias generation is required

If the name is not already legal 8.3, generate alias candidates using strict steps.

The baseline candidate pattern is:

FIRST6~1.EXT

Where:

FIRST6 is normalized/truncated basename prefix
~1 is initial numeric tail
.EXT is extension if one exists, truncated to max 3

No extension? Then no trailing dot/extension segment.

Dot handling is where most bugs hide

Real filenames can contain multiple dots, trailing dots, and decorative punctuation. The rules must be explicit:

skip leading . characters
allow only one basename/extension separator in 8.3
prefer the last dot that has valid non-space characters after it
if name ends with a dot, ignore that trailing dot and use a previous valid dot if present

This is the difference between deterministic behavior and parser folklore.

Example intuition:

report.final.v3.txt -> extension source is last meaningful dot before txt
archive. -> trailing dot is ignored; extension may end up empty

Character legality and normalization

Normalization from the spec includes:

remove spaces and extra dots
uppercase letters using active OEM code page semantics
drop characters that are not representable/legal for short names

Disallowed characters include control chars and:

" * + , / : ; < = > ? [ \ ] |

A critical note from the rules:

Microsoft-documented NT behavior: [ ] + = , : ; are replaced with _ during short-name generation
other illegal/superfluous characters are removed

If your toolchain mixes “replace” and “remove” without policy, you will drift from expected aliases.

Collision handling is an algorithm, not a guess

The collision rule set is precise:

try ~1
if occupied, try ~2, ~3, …
as tail digits grow, shrink basename prefix so total basename+tail stays within 8 chars
continue until unique in the directory

That means ~10 and ~100 are not formatting quirks. They force basename compaction decisions.

A common implementation failure is forgetting to shrink prefix when suffix width grows. The result is invalid aliases or silent truncation.

A deterministic translator skeleton

The following Pascal-style pseudocode keeps policy explicit:

function MakeShortAlias(const LongName: string; const Existing: TStringSet): string;
var
  BaseRaw, ExtRaw, BaseNorm, ExtNorm: string;
  Tail, PrefixLen: Integer;
  Candidate: string;
begin
  SplitUsingDotRules(LongName, BaseRaw, ExtRaw);   { skip leading dots, last valid dot logic }
  BaseNorm := NormalizeBase(BaseRaw);              { remove spaces/extra dots, uppercase, legality policy }
  ExtNorm  := NormalizeExt(ExtRaw);                { uppercase, legality policy, truncate to 3 }

  if IsLegal83(BaseNorm, ExtNorm) and (not Existing.Contains(Compose83(BaseNorm, ExtNorm))) then
  begin
    MakeShortAlias := Compose83(BaseNorm, ExtNorm);
    Exit;
  end;

  Tail := 1;
  repeat
    PrefixLen := 8 - (1 + Length(IntToStr(Tail))); { room for "~" + digits }
    if PrefixLen < 1 then PrefixLen := 1;
    Candidate := Copy(BaseNorm, 1, PrefixLen) + '~' + IntToStr(Tail);
    Candidate := Compose83(Candidate, ExtNorm);
    Inc(Tail);
  until not Existing.Contains(Candidate);

  MakeShortAlias := Candidate;
end;

This intentionally leaves NormalizeBase, NormalizeExt, and SplitUsingDotRules as separate units so policy stays testable.

Table-driven tests beat intuition

Our fictional team fixed its pipeline by building a test corpus, not by debating memory:

Input Component                         Expected Shape
--------------------------------------  ------------------------
README.TXT                              README.TXT
very long filename.txt                  VERYLO~1.TXT
archive.final.build.log                 ARCHIV~1.LOG
...hiddenprofile                        HIDDEN~1
name with spaces.and.dots...cfg         NAMEWI~1.CFG

The exact alias strings can vary with existing collisions and code-page/legality policy details, but the algorithmic behavior should not vary.

Why this matters in operational pipelines

Shortname translation touches many workflows:

installer scripts that reference legacy names
backup/restore verification against manifests
cross-tool compatibility between VFAT-aware and strict 8.3 utilities
reproducible release artifacts

If alias generation is non-deterministic, two developers can build “same version” media with different effective filenames.

That is a release-management nightmare.

The fictional incident response

In our story, the break happened during a Friday packaging run. By Saturday morning, three teams had three conflicting explanations:

“the verifier is wrong”
“Windows generated weird aliases”
“someone copied files manually”

By Saturday afternoon, a tiny deterministic translator plus collision-aware tests cut through all three theories. The verifier was correct, alias generation differed between tools, and manual copies had introduced namespace collisions in one directory.

Nobody needed blame. We needed rules.

Subtle rule: legality depends on OEM code page

One more important caveat from the spec:

Uppercasing and character validity are evaluated in active OEM code page context.

That means “works on my machine” can still fail if code-page assumptions differ. For strict reproducibility, pin the environment and test corpus together.

Practical implementation checklist

For a robust translator:

process one path component at a time
implement legal-8.3 fast path first
codify dot-selection/trailing-dot behavior exactly
separate remove-vs-replace character policy clearly
enforce extension max length 3
implement collision tail growth with dynamic prefix shrink
ship fixture tests with occupied-directory scenarios

That last point is non-negotiable. Most alias bugs only appear under collision pressure.

Closing scene

Our weekend story ends around 01:03 on Sunday. The final verification pass prints green across every directory. The whiteboard still looks chaotic. The room still smells like old plastic and instant coffee. But now the behavior is explainable.

Long names can still be expressive. Short names can still be strict. The bridge between them does not need magic. It needs documented rules and testable translation.

In DOS-era engineering, that is usually the whole game: reduce mystery, increase repeatability, and let simple tools carry serious work.

Related reading:

C:\ After Midnight: A DOS Chronicle

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

There is a particular blue that only old screens know how to make. Not sky blue, not electric blue, not any brand color from modern design systems. It is the blue of waiting, the blue of discipline, the blue of possibility. It is the blue that appears when a machine, after clearing its throat with a POST beep, hands you a bare prompt and says: now it is your turn.

C:\>

No dock, no notifications, no assistant bubble, no pretense of helping you think. Only an invitation and a challenge. The operating system has done almost nothing. You must do the rest.

This is not an article about nostalgia as decoration. It is about a working world that existed inside limits so hard they became architecture. A world where your startup sequence was a design document, your tools fit on a few floppies, your failures had names, and your victories often looked like reclaiming 37 kilobytes of conventional memory so a game or compiler could start. It is also a story, because DOS was never just a technical environment. It was a culture of rituals: boot rituals, backup rituals, anti-virus rituals, debugging rituals, and social rituals that happened in school labs, basements, bedrooms, and noisy clubs where people traded disks like rare books.

So let us spend one long night there. Let us walk into a fictional but faithful 1994 room that smells like warm plastic and printer paper. Let us build and run a complete DOS life from dusk to dawn. Every choice in this chronicle is plausible. Most of them were common. Some of them were mistakes. All of them are true to the era.

18:42 - The Room Before Boot

The desk is too small for the machine, so the machine dominates. A beige tower sits on the floor, wearing scratches and an “Intel Inside” sticker that has started to peel at one corner. On top of the tower rests a second floppy box because the first one filled months ago. A 14-inch CRT sits forward like a stubborn old TV. Behind it, cables twist into an unplanned knot that no one wants to touch because everything still works, somehow.

The keyboard is heavy enough to qualify as carpentry. Its space bar has a polished shine at the center where years of thumbs erased texture. The mouse is optional, often unplugged, because many tasks are faster from keys alone. To the right: a stack of 3.5-inch disks labeled in pen. Some labels are clear: “TP7”, “NORTON”, “PKZIP”, “DOOM WADS”. Some are warnings: “DO NOT FORMAT”, “GOOD BACKUP”, “MAYBE VIRUS”. To the left: a notebook with IRQ tables, command aliases, half-finished phone numbers for BBS lines, and hand-drawn flowcharts for batch menus.

The machine itself is a practical compromise:

486DX2/66
8 MB RAM
420 MB IDE hard drive
Sound Blaster 16 clone
SVGA card with 1 MB VRAM
2x CD-ROM that reads when it feels respected

Nothing here is top-tier for magazines, but it is elite for doing real work. This system can compile, dial, play, and occasionally multitask if treated carefully. It can also punish impatience instantly.

You sit down. You press power.

18:43 - The Beep, the Count, the Oath

Fans spin, drives click, and the BIOS begins its ceremony. Memory counts upward in white text. This number matters because it is the first confirmation that the machine woke up with all its limbs attached. Any stutter means a module might be loose. Any weird symbol means deeper trouble. Any silence from the speaker means fear.

Then the beep arrives. One short beep: the civil peace of hardware has been declared. A double or triple pattern would mean war. You learn these codes the way sailors learn cloud shapes.

IDE detection takes a breath. The hard disk appears. The floppy controller appears. Sometimes the CD-ROM hangs here if the cable is old or the moon is wrong. Tonight it passes.

The bootloader takes over. DOS emerges. No loading animation. No marketing. Just text and trust.

Before anything else, you watch startup lines for anomalies:

Did HIMEM.SYS load?
Did EMM386 complain?
Did mouse.com detect hardware?
Did MSCDEX hook the CD drive?
Did SMARTDRV report cache enabled?

Every message is operational telemetry. If one line changes unexpectedly, your evening plans might collapse. A failed memory manager means no game. A failed CD extension means no install. A failed sound driver means a silent night, and in DOS a silent night is not peaceful, it is broken.

The prompt finally settles. You are in. And the first thing you do is not launch software. You verify your environment.

18:47 - CONFIG.SYS, Constitution of a Small Republic

In DOS, policy is not hidden in control panels. Policy lives in startup files. CONFIG.SYS is constitutional law: memory managers, file handles, buffers, shell behavior, and boot menus if you are ambitious. One bad line can make the system unusable. One smart line can unlock impossible combinations.

Tonight’s CONFIG.SYS is the result of months of tuning:

DOS=HIGH,UMB
DEVICE=C:\DOS\HIMEM.SYS /TESTMEM:OFF
DEVICE=C:\DOS\EMM386.EXE NOEMS I=B000-B7FF
FILES=40
BUFFERS=25
LASTDRIVE=Z
STACKS=9,256
SHELL=C:\DOS\COMMAND.COM C:\DOS\ /E:1024 /P
DEVICEHIGH=C:\DOS\SETVER.EXE

Nothing here is accidental. DOS=HIGH,UMB pushes DOS itself into high memory and opens upper memory blocks. NOEMS is a strategic choice because expanded memory support can cost conventional memory and not every program needs it. I=B000-B7FF reclaims monochrome text memory as usable UMB on compatible hardware. FILES and BUFFERS are set just high enough to avoid common failures but not so high that memory leaks from your hands. SHELL extends environment size because big batch systems starve with tiny defaults.

In modern systems, configuration often feels reversible, low stakes, almost playful. In DOS, editing startup files is surgery under local anesthesia. You save. You reboot. You read every line. You compare free memory before and after.

People who never lived in this environment often assume the difficulty was primitive. It was not primitive. It was explicit. DOS showed consequences immediately. That is harder and better.

19:02 - AUTOEXEC.BAT, Morning Ritual in Script Form

If CONFIG.SYS is law, AUTOEXEC.BAT is routine. This file choreographs the moment your system becomes yours. It sets PATH, initializes drivers, chooses prompt style, maybe launches a menu, maybe starts a TSR for keyboard layouts, maybe does ten things no GUI startup manager would dare expose.

Tonight’s file begins simple:

@ECHO OFF
PROMPT $P$G
PATH C:\DOS;C:\UTIL;C:\TP\BIN
SET TEMP=C:\TEMP
SET BLASTER=A220 I5 D1 H5 T6
LH C:\DOS\MSCDEX.EXE /D:MSCD001 /L:E
LH C:\MOUSE\MOUSE.COM
LH C:\DOS\SMARTDRV.EXE 2048

Then comes the menu system. Not because menus are necessary, but because everyone eventually gets tired of typing long paths and forgetting switch combinations. A good startup menu turns a machine into an instrument.

Option 1: “Work” profile. Loads editor helper TSRs, no sound extras, max conventional memory for compiler.

Option 2: “Play” profile. Loads joystick and sound helpers, reduced disk cache, game launcher.

Option 3: “Clean” profile. Minimal drivers, troubleshooting mode, used when something is broken and you need the smallest reproducible boot.

This is DevOps, 1994 edition: reproducible runtime states encoded in batch files and discipline. No YAML required. No orchestration stack. Just precise ordering and complete responsibility.

19:18 - The 640K Myth and the Real Memory War

People quote “640K ought to be enough for anyone” even though the attribution is dubious. The quote survives because the number was real pain. Conventional memory is the first 640 KB of address space where many DOS programs must live. Everything competes for it: drivers, TSRs, command shell, environment block, and your application.

A 1994 machine might have 8 MB or 16 MB total RAM, yet still fail with: “Not enough memory to run this program.” This sounds absurd until you learn memory classes:

Conventional memory (precious)
Upper memory blocks (reclaimable if lucky)
High memory area (small but useful)
Extended memory (XMS, accessible via manager)
Expanded memory (EMS, bank-switched emulation or hardware)

You become a cartographer. You run MEM /C /P and stare at address ranges like a city planner. You ask hard questions:

Why is CD-ROM support consuming this much?
Can mouse driver move to UMB?
Is SMARTDRV worth its footprint tonight?
Does this game require EMS, or does EMS only hurt us?

Optimization is not abstract. It is measured in single kilobytes and concrete tradeoffs. Reclaiming 12 KB can be the difference between launching and failing. Reclaiming 40 KB feels like finding a hidden room in your house.

The lesson scales. When resources are finite and visible, engineering skill sharpens. You cannot hide inefficiency behind “just add more RAM.” You have to understand what each component does. DOS taught this brutally and effectively.

19:37 - Device Drivers as Characters in a Drama

Every driver has personality. Some are polite and tiny. Some are loud and hungry. Some lie about compatibility.

Your mouse driver might report “v8.20 loaded” with cheerful certainty while occasionally freezing in one specific game. Your CD-ROM driver might work only if loaded before a specific cache utility. Your sound card initialization utility might insist on IRQ 7 while the printer port already has political claim to it.

A mature DOS setup feels less like software installation and more like coalition government. You negotiate resources:

IRQ lines
DMA channels
I/O addresses
upper memory slots

You keep a written table in a notebook because forgetting one assignment can cost hours. The canonical line for Sound Blaster compatibility is sacred:

SET BLASTER=A220 I5 D1 H5 T6

Change one number blindly and half your games lose voice or effects. Worse: some keep running with wrong audio, so you debug by listening for missing explosions.

What modern systems abstract away, DOS made audible. Conflict had texture. Misconfiguration had timbre. When everything aligned, the first digital speech sample from a game intro sounded like victory.

20:05 - Building a Launcher Worth Keeping

Tonight’s major project is not a game and not a compiler. It is a launcher: a better front door for everything else. You start with MENU.BAT, then split logic into modular files:

M_BOOT.BAT for profile setup
M_GAMES.BAT for game categories
M_DEV.BAT for tools and compilers
M_NET.BAT for modem and BBS utilities
M_UTIL.BAT for diagnostics and backup

You draw the menu tree on paper first. This matters. Without a map, batch files become spaghetti faster than any modern scripting language.

Core techniques:

CHOICE /C:12345 /N for deterministic input
IF ERRORLEVEL checks in descending order
temporary environment variables for context
CALL to return from submenus
a shared CLS and header routine for consistency

You include guardrails:

check whether expected directory exists before launch
print useful error if executable missing
return cleanly rather than dropping to random path

At 20:41, you have version one. It is ugly. It works. It feels luxurious.

A modern reader may smile at this effort for “just a menu.” That reaction misses the point. Interface is leverage. A good launcher saves friction every day. In DOS, where every command is explicit, reducing friction means preserving focus.

20:58 - Floppy Disks and the Economy of Scarcity

Storage in DOS culture has sociology. You do not merely “save files.” You classify, rotate, compress, duplicate, and label. A 1.44 MB floppy is tiny, but when it is all you have in your pocket, it becomes a strategy game.

You carry disk sets:

Installer sets (Disk 1..n)
Backup sets (A/B weekly rotation)
Utility emergency disk (bootable, with key tools)
Transfer disk (for school, friends, office)
Risk disk (unknown files, quarantine first)

Compression is standard behavior, not optimization theater. PKZIP -ex is used because every kilobyte matters. Self-extracting archives are convenience gold. Multi-volume archives are often necessary and frequently cursed when one disk in the chain develops a bad sector.

Disk labels are metadata. Good labels include date, version, and source. Bad labels say “stuff” and create archeology digs months later.

Copy verification matters. You learn to distrust successful completion messages from cheap media. So you test restore paths. You compute CRC when possible. You attempt extraction before declaring backup complete.

This discipline feels old-fashioned until you see modern teams lose data because they never practiced recovery. DOS users practiced recovery constantly, because media failure was common and unforgiving. Reliability was not promised; it was engineered by habit.

21:26 - The BBS Hour

At night the modem becomes a portal. You launch terminal software, check initialization string, and listen. Dial tone. Digits. Carrier negotiation song. Static. Then connection: maybe 2400, maybe 9600, maybe luck grants 14400.

Bulletin board systems are part library, part arcade, part neighborhood. Each board has personality:

strict sysop rules and curated files
chaotic message bases with philosophical flame wars
niche communities for one game, one language, one region
elite boards with ratio systems and demanding etiquette

You do not browse infinitely. Phone bills are real constraints. So you arrive with intent:

Upload contribution first (new utility, bugfix, walkthrough).
Download target files using queued protocol.
Read priority messages.
Log off cleanly.

Transfer protocols matter:

XMODEM for compatibility
YMODEM for batch
ZMODEM for speed and resume convenience

A failed transfer at 97 percent can ruin your mood for an hour. A clean ZMODEM session feels like winning a race.

BBS culture taught social engineering before that term became security jargon. Reputation mattered. You gained trust by contributing, documenting, and not uploading garbage. You lost trust quickly by ignoring standards. Moderation existed, but mostly through sysop judgment and local norms. Communities were smaller, more accountable, and often surprisingly generous.

22:03 - Editors, Compilers, and the Craft Loop

Now the serious work begins: coding. Tonight’s project is a small “ship log” program for a sci-fi tabletop campaign. Requirements:

store captain name
append mission entries
show entries with timestamp
export as text

Turbo Pascal launches nearly instantly. That speed changes behavior. You iterate more because compile-run cycles are cheap. You write one function, test immediately, adjust, repeat.

The editor is not modern, but it is coherent. Keyboard-first navigation. Predictable menus. No plugin maze. No dependency download. The machine’s whole attitude says: write code now.

You draft data structures. You remember fixed-size arrays before dynamic containers. You choose records with clear field lengths because memory is budget. You learn to think in layouts, not abstractions detached from cost.

By 22:44 you hit a bug: timestamps show garbage in exported file. Root cause: uninitialized variable in formatting routine. Fix: explicit initialization and bound checks. No framework catches this for you. You catch it by reading your own code carefully and validating outputs.

DOS development gave many people their first honest relationship with determinism. Programs did exactly what you wrote, not what you intended. That gap is where craftsmanship lives.

22:58 - Debugging Without Theater

There is a clean beauty in simple debugging tools. No telemetry stack. No cloud traces. No billion-line logs. Just targeted prints, careful reasoning, and binary search through code paths.

Tonight you test file append behavior under stress. You generate 500 entries, each with varying length. Expected outcome before run:

no truncated records
file size increases predictably
UI list remains responsive
no crash on boundary at max entries

Observed outcome:

records above 255 chars truncate
size increments mostly predictably but with occasional mismatch
UI slows but survives
boundary condition crashes on entry 501

Difference analysis:

one-byte length assumption leaked from old helper routine
boundary check uses > where >= was required
mismatch due to newline handling inconsistency between display and export

You fix each issue, rerun same test, compare against expected behavior again. This discipline is timeless: predict, observe, explain difference, adjust. DOS did not invent it, but DOS rewarded it fast.

When toolchains are thin, your method matters more. That is a gift disguised as inconvenience.

23:31 - Games as Hardware Diagnostics

Around midnight, development pauses and diagnostics begin, disguised as fun. A few game launches can tell you more about system health than many utilities.

Game A checks memory layout sensitivity. Game B checks sound card IRQ/DMA sanity. Game C checks VGA mode compatibility. Game D checks CD streaming and disk throughput.

You keep a mental matrix:

If digital effects work but music fails, inspect MIDI config.
If intro videos stutter, inspect cache and drive mode.
If joystick drifts, recalibrate and verify gameport noise.
If random crashes appear only in one title, suspect EMS/XMS setting mismatch.

This is why old forum advice often started with “what games fail?” Games were comprehensive integration tests for consumer PCs. They touched timing, graphics, audio, input, memory, disk, and often copy-protection edge cases.

Tonight one title locks after logo. You troubleshoot:

Run clean boot profile.
Disable EMM386.
Change sound IRQ from 5 to 7 in setup utility.
Re-test.

It works on step 3. Root cause: hidden conflict with network card TSR loaded in play profile. You update documentation notebook accordingly.

Modern systems can hide this complexity. DOS made you model it. That modeling skill transfers directly to contemporary incident response.

00:04 - Dot Matrix Midnight and the Sound of Output

At 00:04, the house is quiet enough that printing feels illegal. Yet you print anyway, because paper is still the best way to review long code and BBS message drafts.

The dot matrix wakes like a factory machine: tractor feed catches, head moves with aggressive rhythm, pins strike ribbon, letters appear in a texture that looks more manufactured than drawn.

Printing in DOS is deceptively simple. COPY FILE.TXT LPT1 might be enough. Until it is not.

Common realities:

printer expects different control codes
line endings cause ugly wrapping
graphics mode drivers consume huge memory
bidirectional cable quality affects reliability

You learn escape sequences for bold, condensed, reset. You keep a tiny utility for form feed. You clear stalled print jobs by power-cycling in exactly the right order.

The printer is loud, yes, but also clarifying. When output becomes physical, you read with different care. Typos that survived on screen jump out on paper. Overlong variable names and awkward menu copy suddenly offend.

In a strange way, this analog detour improves digital quality. DOS workflows were full of such loops: constrained media forcing deliberate review.

00:37 - Viruses, Trust, and Street-Level Security

Security in DOS culture is local, immediate, and personal. Threats arrive on floppy disks, BBS downloads, and borrowed game collections. There are no automatic background updates. There is only your process.

Typical defense ritual:

Boot from trusted clean floppy.
Run scanner against suspect media.
Inspect boot sectors.
Copy only necessary files.
Re-scan destination.

You maintain a “quarantine” directory and never execute unknown binaries directly from incoming disks. You keep checksums for critical utilities. You write-protect master install disks physically whenever possible.

Social trust is part of security posture. Files from known sysops carry more confidence. Random archives with dramatic names do not. Executable games with no documentation are suspicious.

Many users learn the hard way after first infection:

altered boot records
strange memory residency
disappearing files
unexpected messages at startup

Recovery is painful enough that habits change. People who lived through this era often become very good at skeptical intake and layered backup. When every machine is a kingdom with weak walls, you learn gatekeeping.

DOS security was imperfect and often bypassed. But it trained a mindset modern convenience sometimes erodes: assume nothing is safe by default.

01:03 - The Aesthetic of Plain Text

DOS taught an underrated design lesson: plain text scales astonishingly far. Configuration, scripts, notes, source code, logs, to-do lists, and even mini databases often live as text. Text is inspectable, diffable (even by eyeballing), compressible, and recoverable.

Binary formats exist, of course, but text remains the backbone. You can open a .BAT in any editor. You can parse your own logs with one-liners. You can rescue important data from partially damaged files more often than with opaque binaries.

Tonight you migrate your project notes from scattered files into one structured log:

TODO.TXT
BUGS.TXT
IDEAS.TXT
HARDWARE.TXT

Each file starts with date-prefixed entries. No tooling dependency. No schema migration. No vendor lock.

This is not anti-progress. It is strategic minimalism. When formats are simple, system longevity improves. A file you wrote in 1994 can often still be read in 2026 without conversion pipelines. That is remarkable durability.

The modern web rediscovered this truth through markdown and plaintext knowledge bases. DOS users had no choice, and therefore learned it deeply.

01:28 - Naming, Paths, and the Poetry of 8.3

Filenames in classic DOS often follow 8.3 constraints: up to eight characters, dot, three-character extension. People mock it as primitive. It is. It is also a forcing function for concise naming.

Conventions emerge:

README.TXT for human orientation
INSTALL.BAT for setup entry
CFG for config
DOC for manuals
PAS and ASM for source

You become intentional about directory hierarchy because deep nesting is painful and long names are unavailable. A good tree might look like:

C:\WORK\SHIPLOG
C:\GAMES\SIM
C:\UTIL\ARCHIVE

Even with constraints, creativity leaks through:

NITEBOOT.BAT for midnight profile
FIXIRQ.BAT for emergency audio reset
SAFECPY.BAT for verified copy with logging

Limited naming can improve shared understanding. A teammate opening your disk does not need a wiki to locate essentials. Clarity lives in path design.

In modern systems, we enjoy long names and Unicode. That is good progress. But the DOS lesson remains: name things so a tired human can navigate at 2 AM with no context.

01:54 - A Small Disaster and a Better Backup Plan

No long DOS night is complete without a scare. Tonight it comes from a hard disk click pattern you recognize and hate. A utility write operation stalls. Directory listing returns slowly. Then one file shows corrupted size.

Panic is natural. Protocol is better.

Immediate response:

Stop all writes.
Reboot from trusted floppy.
Run disk check in read-only mindset first.
Identify most critical files.
Copy priority data to known-good media.

You lose one cache file and a temporary archive. You save source code, notes, and configuration. Damage is limited because weekly rotation backups existed.

This event triggers policy change. You redesign backup process:

daily incremental to floppy set (work files)
weekly full archive split across labeled disks
monthly “cold” backup stored away from desk
quarterly restore drill to verify process actually works

You also add BACKLOG.TXT to log backup dates and outcomes. Trust now comes from evidence, not intention.

Modern cloud sync can create illusion of safety. It helps, but it is not equivalent to tested restore paths. The DOS era taught this because failure was loud and frequent. Reliability is a practiced behavior, not a subscription feature.

02:21 - Multitasking Dreams and Honest Limits

By 1994, many users tasted GUI multitasking through Windows, OS/2, or DESQview. Still, pure DOS sessions remained where speed and control mattered most. People asked the same question we ask now in different form: can I do everything at once?

In DOS, the answer is mostly no, and that honesty is refreshing. Foreground program owns the machine. TSRs fake multitasking for narrow tasks: keyboard helpers, print spoolers, clipboards, pop-up calculators. Beyond that, context switches are human, not scheduler-driven.

This limitation changes behavior:

You plan task order.
You finish one operation before starting the next.
You script repetitive work.
You avoid background complexity unless necessary.

Productivity becomes sequence design. You think in pipelines:

edit -> compile -> test -> package -> transfer.

When every step is explicit, wasted motion becomes visible. Many modern productivity problems are not missing features. They are hidden sequence costs. DOS users felt sequence costs constantly and therefore optimized habit.

Constraint can be cognitive ergonomics. Not always. But often enough to be worth remembering.

02:46 - Hardware Surgery at Night

At 02:46 you do the thing everyone swears not to do late at night: open the case. Reason: intermittent audio pop that software fixes did not solve.

Static precautions are improvised but sincere: touch grounded metal, avoid carpet shuffle, move slowly.

Inside, the machine is a geography lesson:

ribbon cables folded like paper roads
ISA cards seated with uncertain confidence
dust colonies around heatsink and fan

You reseat the sound card. You inspect jumper settings against your notebook. You notice one jumper moved slightly off expected pins, probably from vibration over years. You correct it, close case, reboot, test.

Problem gone.

This is not romantic. It is practical literacy. Users in this era often crossed boundaries between software and hardware because they had to. That cross-layer awareness is rare now, and teams pay for its absence with slow diagnostics and tribal silos.

When you physically touch the subsystem you configure, abstractions become real. IRQ is no longer “some setting.” It is a finite line negotiated by components you can point to.

03:12 - The Long Build and the Quiet Concentration

The rest of the night is steady work. No big events. No drama. Just compiles, tests, edits, and notes. This is where craft actually happens.

You refine the ship log tool:

add search by captain
add compact list mode
improve export formatting
add command-line switches for batch usage

You write usage docs in plain text. You include examples. You include known limitations. You include version history with dates. Future-you will be grateful.

By 03:58, version 0.9 feels stable. You package distribution:

PKZIP SHIPLOG09.ZIP *.EXE *.TXT *.CFG

Then you test install in a clean directory from archive, exactly as another user would. Expected outcome:

unpack cleanly
run without additional files
generate default config if missing

Observed outcome:

unpack cleanly
startup fails if TEMP variable undefined

Fix:

add fallback to current directory when TEMP absent
update docs
repack as 0.9a

That extra test saves your reputation later. Most software quality wins come from boring verification, not heroic debugging.

04:17 - Why This Era Made Strong Builders

It is tempting to read all this as old-tech cosplay. That would be shallow. The deeper value of DOS is pedagogical. It forced visibility of system layers and cost models:

startup order mattered
resource allocation was finite and inspectable
interfaces were simple but composable
failure modes were direct and attributable

From this environment, people learned transferable habits:

Observe before acting.
Document assumptions.
Build reproducible workflows.
Test from clean states.
Treat backup and recovery as first-class engineering.

Modern stacks are far more capable and complex. Good. But complexity without visibility can weaken operator intuition. That is why retro practice still helps. It is not about rejecting progress. It is about training mental models on a system small enough to understand end to end.

If you can reason about a DOS boot chain and memory map, you are better prepared to reason about container startup orders, dependency graphs, and runtime budgets today. The scale changed. The logic did not.

04:39 - Rebuilding the Experience in 2026

Suppose you want this learning now, not as museum nostalgia but as active practice. You can recreate a meaningful DOS environment in an evening.

Practical approach:

Use an emulator (DOSBox-X or PCem-class tools if you want lower-level authenticity).
Install MS-DOS compatible environment (or FreeDOS for legal convenience).
Build from scratch:
- text editor
- archiver
- compiler/interpreter
- file manager
- diagnostics utilities
Write your own CONFIG.SYS and AUTOEXEC.BAT rather than copying premade blobs.
Keep a real notebook for IRQ/port/memory notes.

Learning exercises worth doing:

reclaim conventional memory for a demanding app
create boot menu profiles for different tasks
script a full backup and verify restore
build one useful command-line tool in Pascal, C, or assembly
document and fix one intentional misconfiguration

Expected outcomes if done seriously:

stronger intuition for startup/runtime boundaries
better troubleshooting sequence discipline
improved empathy for low-resource systems
renewed appreciation for explicit tooling

This is not mandatory for modern development. It is high-return training if you enjoy systems thinking.

05:03 - Dawn, Prompt, and Continuity

The sky outside shifts from black to gray. You have been awake through one complete cycle of your machine and your own attention. Nothing in this room has gone viral. No dashboard celebrated your streak. No cloud service congratulated your retention. Yet real progress happened:

a tuned boot environment
a cleaner launcher
a tested utility release
documented fixes
improved backup policy

You type one last command:

DIR C:\WORK\SHIPLOG

Files listed. Dates updated. Sizes plausible. No surprises.

Then:

C:\>EXIT

Monitor clicks to black. Room goes quiet except for fan spin-down.

What remains is not merely data. It is a learned posture: respect constraints, prefer clarity, test assumptions, document reality, build tools that serve humans under pressure.

That posture is timeless. It worked on DOS. It works now.

Appendix - Midnight Recipes from the Notebook

Because every DOS chronicle should end with practical scraps, here are compact recipes that earned permanent place in my notebook.

1) Fast memory sanity check

1
2
3

@ECHO OFF
MEM /C /P
PAUSE

Use before and after startup edits. Do not trust memory “feelings”; trust measured deltas.

2) Safer copy with verification

@ECHO OFF
IF "%1"=="" GOTO usage
IF "%2"=="" GOTO usage
COPY %1 %2
IF ERRORLEVEL 1 GOTO fail
FC /B %1 %2 >NUL
IF ERRORLEVEL 1 GOTO fail
ECHO VERIFIED: %1 -> %2
GOTO end
:fail
ECHO COPY OR VERIFY FAILED
GOTO end
:usage
ECHO USAGE: SAFECPY source target
:end

Not elegant, but good enough to prevent silent corruption surprises.

:menu
CLS
ECHO [1] Work
ECHO [2] Games
ECHO [3] Tools
ECHO [4] Exit
CHOICE /C:1234 /N /M "Select:"
IF ERRORLEVEL 4 GOTO done
IF ERRORLEVEL 3 GOTO tools
IF ERRORLEVEL 2 GOTO games
IF ERRORLEVEL 1 GOTO work
GOTO menu

Descending ERRORLEVEL checks save hours of subtle bugs.

4) Packaging checklist

Build from clean boot profile.
Delete temp artifacts.
Zip binaries, docs, sample config.
Extract into empty directory and run there.
Confirm defaults for missing environment variables.
Write changelog entry before upload.

A release is not complete when it compiles. A release is complete when someone else can use it without guessing.

5) Two golden notes

“If it only works on your machine, it is not done.”
“If you cannot restore it, you do not have it.”

These notes survived every platform transition I have lived through.

Final Reflection

The DOS era is often described with a grin and a shrug: primitive, charming, inconvenient. Those words are not wrong, but they are incomplete. It was also rigorous, educative, and deeply empowering for anyone willing to understand the machine as a layered system instead of a magic appliance.

When you stare at a plain prompt, there is nowhere to hide. You either know what happens next, or you learn. That directness is rare now. It is worth preserving.

So if you ever find yourself inside a retro setup at 2 AM, cursor blinking, no GUI in sight, do not treat it as reenactment. Treat it as training. Build something small. Tune something real. Break something recoverably. Write down what happened. Then do it again until cause and effect become instinct.

The old blue screen will not flatter you. It will teach you.

Related reading:

CONFIG.SYS as Architecture

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

In DOS culture, CONFIG.SYS is often remembered as a startup file full of cryptic lines. That memory is accurate and incomplete. In practice, CONFIG.SYS was architecture: a compact declaration of runtime policy, resource allocation, compatibility strategy, and operational profile.

Before your application loaded, your architecture was already making decisions:

memory model and address space usage
device driver ordering
shell environment limits
compatibility shims
profile selection at boot

The shape of your software experience depended on this pre-application contract.

Take a typical line like:

DOS=HIGH,UMB

This is not a minor tweak. It is a policy statement about reclaiming conventional memory by relocating DOS and enabling upper memory blocks. The decision directly affects whether demanding software starts at all. On constrained systems, architecture is measurable in kilobytes.

Similarly:

DEVICE=C:\DOS\EMM386.EXE NOEMS

The NOEMS option is a strategic compatibility choice. Some programs require EMS, others run better without the overhead. Choosing this setting without understanding workload is equivalent to shipping an environment optimized for one use case while silently degrading another.

The best DOS operators treated boot configuration like environment design:

define target workloads
map resource constraints
choose defaults
create profile variants
validate with repeatable test matrix

That process should sound familiar to anyone running modern deployment profiles.

Order mattered too. Driver initialization sequence could change behavior materially. A mouse driver loaded high might free memory for one app. Loaded low, it might block a game from launching. CD extensions, caching layers, and compatibility utilities formed a boot dependency graph, even if no one called it that.

Dependency graphs existed long before package managers.

FILES=, BUFFERS=, and STACKS= lines are another example of policy in disguise. Too low, and software fails unpredictably. Too high, and scarce memory is wasted. Right-sizing these parameters required understanding workload behavior, not copying internet snippets.

This is why blindly sharing “ultimate CONFIG.SYS” templates often failed. Configurations are context-specific.

Boot menus made this explicit:

profile A for development tools
profile B for memory-hungry games
profile C for diagnostics

Each profile encoded a different architecture for the same machine. Modern analogy: environment-specific manifests for build, test, and production. Same codebase, different runtime envelopes.

Reliability also improved when teams documented intent inline. A comment like “NOEMS to maximize conventional memory for compiler” prevents accidental reversal months later. Without intent, configuration files become superstition archives.

Superstition-driven config is fragile by definition.

A practical DOS validation routine looked like:

boot each profile cleanly
run MEM /C and record map
execute representative app set
observe startup/exit stability
compare before/after when changing one line

Notice the discipline: one change at a time, evidence over intuition.

Error handling in this layer was unforgiving. Misconfigured drivers could fail silently, partially initialize, or create cascading side effects. Because visibility was limited, operators learned to create minimal recovery profiles with the smallest viable boot path.

That is classic blast-radius control.

There is a deeper lesson here: architecture is not only frameworks and diagrams. Architecture is every decision that constrains behavior under load, failure, and variation. CONFIG.SYS happened to expose those decisions in plain text.

Modern systems sometimes hide these boundaries behind abstractions. Useful abstractions can improve productivity, but hidden boundaries can degrade operator intuition. DOS taught boundary awareness because it had no room for illusion.

You felt every tradeoff:

startup speed versus memory footprint
compatibility versus performance
convenience drivers versus deterministic behavior

Those tradeoffs still define system design, only at different scales.

Another quality of CONFIG.SYS is deterministic startup. If boot succeeded and expected modules loaded, runtime assumptions were fairly stable. That determinism made troubleshooting tractable. In modern distributed stacks, we often lose this simplicity and then pay for observability infrastructure to recover it.

The takeaway is not “go back to DOS.” The takeaway is to preserve explicitness:

declare startup assumptions
document resource policies
version environment configurations
test profile variants routinely
maintain a minimal safe-mode path

These practices transfer directly.

A surprising amount of incident response pain comes from undocumented environment behavior. DOS users could not afford undocumented behavior because failures were immediate and local. We can still adopt that discipline voluntarily.

If you revisit CONFIG.SYS today, read it as a tiny architecture document:

what the system prioritizes
what compatibility it chooses
how it handles scarcity
how it recovers from misconfiguration

Those are architecture questions in any era.

The file format may look old, but the thinking is modern: explicit policies, constrained resources, and testable configuration states. Good systems engineering has always looked like this.

Interrupts as User Interface

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

In modern systems, user interface usually means windows, widgets, and event loops. In classic DOS environments, the interface boundary often looked very different: software interrupts. INT calls were not only low-level plumbing; they were stable contracts that programs used as operating surfaces for display, input, disk services, time, and devices.

Thinking about interrupts as a user interface reveals why DOS programming felt both constrained and elegant. You were not calling giant frameworks. You were speaking a compact protocol: registers in, registers out, carry flag for status, documented side effects.

Take INT 21h, the core DOS service API. It offered file IO, process management, memory functions, and console interaction. A text tool could feel interactive and polished while relying entirely on these calls and a handful of conventions. The interface was narrow but predictable.

INT 10h for video and INT 16h for keyboard provided another layer. Combined, they formed a practical interaction stack:

render character cells
move cursor
read key events
update state machine

That is a full UI model, just encoded in BIOS and DOS vectors instead of GUI widget trees.

The benefit of such interfaces is explicitness. Every call had a cost and a contract. You learned quickly that “just redraw everything” may flicker and waste cycles, while selective redraws feel responsive even on modest hardware.

A classic loop looked like:

read key via INT 16h
map key to command/state transition
update model
repaint affected cells only

This remains good architecture. Event input, state transition, minimal render diff.

Interrupt-driven design also encouraged compatibility thinking. Programs often needed to run across BIOS implementations, DOS variants, and quirky hardware clones. Defensive coding around return flags and capability checks became normal practice.

Modern equivalent? Feature detection, graceful fallback, and compatibility shims.

Error handling through flags and return codes built good habits too. You did not get exception stacks by default. You checked outcomes explicitly and handled failure paths intentionally. That style can feel verbose, but it produces robust control flow when applied consistently.

There was, of course, danger. Interrupt vectors could be hooked by TSRs and drivers. Programs sharing this environment had to coexist with unknown residents. Hook chains, reentrancy concerns, and timing assumptions made debugging subtle.

Yet this ecosystem also taught composability. TSRs could extend behavior without source-level integration. Keyboard enhancers, clipboard utilities, and menu overlays effectively acted like plugins implemented through interrupt interception.

The modern analogy is middleware and event interception layers. Different mechanism, same concept.

Performance literacy was unavoidable. Each interrupt call touched real hardware pathways and constrained memory. Programmers learned to batch operations, avoid unnecessary mode switches, and cache where safe. This is still relevant in latency-sensitive systems.

A practical lesson from INT-era code is interface minimalism. Many successful DOS tools provided excellent usability with:

clear hotkeys
deterministic screen layout
immediate feedback
low startup cost

No animation. No ornamental complexity. Just direct control and predictable behavior.

Documentation quality mattered more too. Because interfaces were low-level, good comments and reference notes were essential. Teams that documented register usage, assumptions, and tested configurations shipped software that survived beyond one machine setup.

If you revisit DOS programming today, treat interrupts not as relics but as case studies in API design:

small surface
explicit contracts
predictable error signaling
compatibility-aware behavior
measurable performance characteristics

These are timeless properties of good interfaces.

There is also a philosophical takeaway: user experience does not require visual complexity. A system can feel excellent when response is immediate, controls are learnable, and failure states are understandable. Interrupt-era tools often got this right under severe constraints.

You can even apply this mindset to current CLI and TUI projects. Build narrow, well-documented interfaces first. Keep interactions deterministic. Prioritize startup speed and feedback latency. Reserve abstraction for proven pain points, not speculative architecture.

Interrupts as user interface is not about romanticizing old APIs. It is about recognizing that good interaction design can emerge from strict contracts and constrained channels. The medium may change, but the principles endure.

When software feels clear, responsive, and dependable, users rarely care whether the plumbing is modern or vintage. They care that the contract holds. DOS interrupts were contracts, and in that sense they were very much a UI language.

IRQ Maps and the Politics of Slots

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

Anyone who built or maintained DOS-era PCs remembers that hardware conflicts were not rare edge cases; they were normal engineering terrain. IRQ lines, DMA channels, and I/O addresses had to be negotiated manually, and each new card could destabilize a previously stable system. This was less like plug-and-play and more like coalition politics in a fragile parliament.

The core constraint was scarcity. Popular sound cards wanted IRQ 5 or 7. Network cards often preferred 10 or 11 on later boards but collided with other devices on mixed systems. Serial ports claimed fixed ranges by convention. Printer ports occupied addresses and IRQs that software still expected. These were not abstract settings. They were finite shared resources, and two devices claiming the same line could produce failures that looked random until you mapped the whole system.

That mapping step separated casual tinkering from reliable operation. Good builders kept a notebook: slot position, card model, jumper settings, base address, IRQ, DMA low/high, BIOS toggles, and driver load order. Without this, every change became archaeology. With it, you could reason about conflicts before booting and recover quickly after experiments.

Slot placement itself mattered more than many people remember. Motherboards often wired specific slots to shared interrupt paths or delivered different electrical behavior under load. Moving a card one slot over could stabilize an entire system. This felt superstitious until you understood board traces, chipset quirks, and timing sensitivities. “Try another slot” was not a meme; it was an informed diagnostic move.

Software configuration had to align with hardware reality. A sound card set to IRQ 5 physically but configured as IRQ 7 in a game setup utility produced symptoms that were confusing but consistent: missing effects, lockups during sample playback, or intermittent crackle. The fix was not mystical. It was alignment across all layers: jumper, driver, environment variable, and application profile.

Boot profiles in CONFIG.SYS and AUTOEXEC.BAT were a practical strategy for managing these tensions. One profile could prioritize networking and tooling, another multimedia and joystick support, another minimal diagnostics with most TSRs disabled. This profile pattern is a direct ancestor of modern environment presets. The principle is the same: explicit runtime compositions for different goals.

DMA conflicts introduced their own flavor of pain. Two devices fighting over transfer channels could produce corruption that looked like software bugs. Audio glitches, disk anomalies, and sporadic crashes were common misdiagnoses. Experienced builders verified resource assignment first, then software assumptions. This order saved hours and prevented unnecessary reinstalls.

Another historical lesson is that documentation quality varied wildly. Some clone cards shipped with sparse manuals or contradictory defaults. Community knowledge filled gaps: magazine columns, BBS archives, user groups, and handwritten cheatsheets. Effective troubleshooting required combining official docs with field reports. This mirrors contemporary reality where vendor documentation and community issue threads jointly form operational truth.

The social side mattered too. In many places, one local expert became the de facto “slot diplomat,” helping classmates, coworkers, or club members resolve impossible-seeming conflicts. These people were not wizards. They were disciplined observers with good records and patience. Their method was repeatable: isolate, simplify, reassign, retest, document.

From a design perspective, this era teaches respect for explicit resource models. Automatic negotiation is convenient, and modern systems rightly hide many details. But when abstraction fails, teams still need people who can reason from first principles. IRQ maps are old, yet the mindset transfers directly to container port collisions, PCI passthrough issues, interrupt storms, and shared resource exhaustion in current stacks.

If you ever rebuild a vintage machine, treat slot planning as architecture, not housekeeping. Define requirements first: audio reliability, network throughput, serial compatibility, low-noise operation, diagnostic observability. Then assign resources intentionally, keep a change log, and resist random edits under fatigue. Stability is usually the outcome of boring discipline, not lucky jumper positions.

The romance of retro hardware often focuses on aesthetics: beige cases, mechanical switches, CRT glow. The deeper craft was operational negotiation under constraint. IRQ maps were part of that craft. They made you model the whole system, validate assumptions layer by layer, and write down what you learned so the next failure started from knowledge, not myth.

That documentation habit is probably the most transferable lesson. Whether you are assigning IRQs on ISA cards or allocating shared resources in modern infrastructure, stable systems are usually the result of explicit maps, deliberate ownership, and controlled change. The names changed. The engineering pattern did not.

Practical IRQ map example

SB16 clone      A220 I5 D1 H5
NE2000 ISA      IRQ10 IO300
COM1/COM2       IRQ4 / IRQ3
LPT1            IRQ7 (disabled if audio needs IRQ7)

The exact values vary by board and card set, but writing this table down before changes prevents blind conflict loops.

Related reading:

Mode 13h in Turbo Pascal: Graphics Programming Without Illusions

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

Turbo Pascal graphics programming is one of the cleanest ways to learn what a frame actually is. In modern stacks, rendering often passes through layers that hide timing, memory layout, and write costs. In DOS Mode 13h, almost nothing is hidden. You get 320x200, 256 colors, and a linear framebuffer at segment $A000. Every pixel you draw is your responsibility.

Mode 13h became a favorite because it removed complexity that earlier VGA modes imposed. No planar bit operations, no complicated bank switching for this resolution, and no mystery about where bytes go. Pixel (x, y) maps to offset y * 320 + x. That directness made it ideal for demos, games, and educational experiments. It rewarded people who could reason about memory as geometry.

A minimal setup in Turbo Pascal is refreshingly explicit: switch video mode via BIOS interrupt, get access to VGA memory, write bytes, wait for input, restore text mode. There is no rendering engine to configure. You control lifecycle directly. That means you also own failure states. Forget to restore mode and you leave the user in graphics. Corrupt memory and artifacts appear instantly.

Early experiments usually start with single-pixel writes and quickly hit performance limits. Calling a procedure per pixel is expressive but expensive. The first optimization lesson is batching and locality: draw contiguous spans, avoid repeated multiplies, precompute line offsets, and minimize branch-heavy inner loops. Mode 13h teaches a truth that still holds in GPU-heavy times: throughput loves predictable memory access.

Palette control is another powerful concept students often miss today. In 256-color mode, pixel values are indices, not direct RGB triples. By writing DAC registers, you can change global color mappings without touching framebuffer bytes. This enables palette cycling, day-night transitions, and cheap animation effects that look far richer than their computational cost. You are effectively animating interpretation, not data.

The classic water or fire effects in DOS demos relied on exactly this trick. The framebuffer stayed mostly stable while the palette rotated across carefully constructed ramps. What looked dynamic and expensive was often elegant indirection. When people say old graphics programmers were “clever,” this is the kind of system-level cleverness they mean: using hardware semantics to trade bandwidth for perception.

Flicker management introduces the next lesson: page or buffer discipline. If you draw directly to visible memory while the beam is scanning, partial updates can tear. So many projects used software backbuffers in conventional memory, composed full frames there, then copied to $A000 in one pass. With tight loops and occasional retrace synchronization, output became dramatically cleaner. This is conceptually the same as modern double buffering.

Collision and sprite systems further sharpen design. Transparent blits require skipping designated color indices. Masking introduces branch costs. Dirty-rectangle approaches reduce full-screen copies at the price of bookkeeping complexity. Developers learned to choose trade-offs based on scene characteristics instead of blindly applying one pattern. That mindset remains essential in performance engineering: no optimization is universal.

Turbo Pascal itself played a practical role in this loop. You could prototype an effect in high-level Pascal, profile by observation, then move only hotspot routines to inline assembly where needed. That incremental path is important. It discouraged premature optimization while still allowing low-level control when measurable bottlenecks appeared. Good systems work often looks like this staircase: clarity first, precision optimization second.

Debugging graphics bugs in Mode 13h was brutally educational. Off-by-one writes painted diagonal scars. Incorrect stride assumptions created skewed images. Overflow in offset arithmetic wrapped into nonsense that looked artistic until it crashed. You learned to verify bounds, separate coordinate transforms from blitting, and build tiny visual test patterns. A checkerboard routine can reveal more than pages of logging.

One underused exercise for modern learners is implementing the same tiny scene three ways: naive per-pixel draw, scanline-optimized draw, and buffered blit with palette animation. The visual output can be identical while performance differs radically. This makes optimization tangible. You are not guessing from profiler flames alone; you see smoothness and latency with your own eyes.

Mode 13h also teaches humility about hardware assumptions. Not every machine behaves the same under load. Timing differences, cache behavior, and peripheral quirks affect results. The cleanest DOS codebases separated device assumptions from scene logic and made fallbacks possible. That sounds like old wisdom, but it maps directly to current cross-platform rendering work.

There is a reason this environment remains compelling decades later. It compresses core graphics principles into a small, understandable box: memory addressing, color representation, buffering strategy, and frame pacing. You can hold the whole pipeline in your head. Once you can do that, modern APIs feel less magical and more like powerful abstractions built on familiar physics.

Turbo Pascal in Mode 13h is therefore not a relic exercise. It is a precision training ground. It teaches you to respect data movement, to decouple representation from display, to optimize where evidence points, and to treat visual correctness as testable behavior. Those lessons survive every framework trend because they are not about tools. They are about first principles.

Mode X in Turbo Pascal, Part 1: Planar Memory and Pages

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

Mode 13h is the famous VGA “easy mode”: one byte per pixel, 320x200, 256 colors, linear memory. It is perfect for first experiments and still great for teaching rendering basics. But old DOS games that felt smoother than your own early experiments usually did not stop there. They switched to Mode X style layouts where planar memory, off-screen pages, and explicit register control gave better composition options and cleaner timing.

This first article in the series is about that mental model. Before writing sprite engines, tile systems, or palette tricks, you need to understand what the VGA memory controller is really doing. If the model is wrong, every optimization turns into folklore.

If you have not read Mode 13h Graphics in Turbo Pascal, do that first. It gives the baseline we are now deliberately leaving behind.

Why Mode X felt “faster” in real games

The practical advantage was not raw arithmetic speed. The advantage was control over layout and buffering:

You could keep multiple pages in video memory.
You could build into a hidden page and flip start address.
You could organize writes in ways that matched planar hardware better.
You could avoid tearing without full-frame copies every frame.

What looked like magic in magazines was mostly disciplined memory mapping plus stable frame pacing.

The key shift: from linear bytes to planes

In Mode X style operation, pixel bytes are distributed across four planes. Adjacent pixel columns are not consecutive memory bytes in the way Mode 13h beginners expect. Instead, pixel ownership rotates by plane. That means one memory offset can represent four neighboring pixels depending on which plane is currently enabled for writes.

The control knobs are VGA registers:

Sequencer map mask: choose writable plane(s).
Graphics controller read map select: choose readable plane.
CRTC start address: choose which memory area is currently displayed.

Once you accept that “address + selected plane = pixel target,” most confusing behavior suddenly becomes deterministic.

Entering a workable 320x240-like unchained setup

Many implementations start by setting BIOS mode 13h and then unchaining to get planar behavior while keeping convenient geometry assumptions. Exact register recipes vary by card and emulator, so treat this as a pattern, not sacred scripture.

procedure SetModeX;
begin
  asm
    mov ax, $0013
    int $10
  end;

  { Disable chain-4 and odd/even, enable all planes }
  Port[$3C4] := $04; Port[$3C5] := $06; { Memory Mode }
  Port[$3C4] := $02; Port[$3C5] := $0F; { Map Mask }

  { Graphics controller tweaks for unchained access }
  Port[$3CE] := $05; Port[$3CF] := $40;
  Port[$3CE] := $06; Port[$3CF] := $05;
end;

Do not panic if this looks low-level. Turbo Pascal is excellent at this style of direct hardware work because compile-run cycles are fast and failures are usually immediately observable.

Plotting one pixel with plane selection

A minimal pixel routine makes the model tangible. X chooses plane and byte offset; Y chooses row stride component.

procedure PutPixelX(X, Y: Integer; C: Byte);
var
  Offset: Word;
  PlaneMask: Byte;
begin
  Offset := (Y * 80) + (X shr 2);
  PlaneMask := 1 shl (X and 3);

  Port[$3C4] := $02;
  Port[$3C5] := PlaneMask;
  Mem[$A000:Offset] := C;
end;

The 80 stride comes from 320/4 bytes per row in planar addressing. That single number is where many beginner bugs hide, because linear assumptions die hard.

Pages and start address flipping

A stronger reason to adopt Mode X is page strategy. If your card memory budget allows it, maintain two or more page regions in VRAM. Render into non-visible page, then point CRTC start address at the finished page. That is cheaper and cleaner than copying full frames through CPU-visible loops every tick.

Conceptually:

displayPage is what CRTC shows.
drawPage is where your renderer writes.
End of frame: swap roles and update CRTC start.

The code details differ by implementation, but the discipline is universal: never draw directly into the page currently being scanned out unless you enjoy tear artifacts as design motif.

Practical debugging advice

When output is wrong, do not “optimize harder.” Validate one axis at a time:

Fill one plane with a color and confirm stripe pattern.
Write known values at fixed offsets and read back by plane.
Verify start-address page flip without any sprite code.
Only then add primitives and scene logic.

This sequence saves hours. Most graphics bugs in this phase are addressing bugs, not “algorithm bugs.”

Where we go next

In Part 2, we build practical drawing primitives (lines, rectangles, clipped blits) that respect planar layout instead of fighting it:

Mode X in Turbo Pascal, Part 2: Primitives and Clipping

Related context:

Mode X is not difficult because it is old. It is difficult because it requires a precise mental model. Once that model clicks, the hardware starts to feel less like a trap and more like an instrument.

Mode X in Turbo Pascal, Part 2: Primitives and Clipping

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

After the planar memory model clicks, the next trap is pretending linear drawing code can be “ported” to Mode X by changing one helper. That works for demos and fails for games. Robust Mode X rendering starts with primitives that are aware of planes, clipping, and page targets from day one.

If you missed the foundation, begin with Part 1: Planar Memory and Pages. This article assumes you already have working pixel output and page flipping.

Primitive design goals

For old DOS rendering pipelines, primitives should optimize for correctness first:

Never write outside page bounds.
Keep clipping deterministic and centralized.
Minimize per-pixel register churn where possible.
Separate addressing math from shape logic.

Performance matters, but undefined writes kill performance faster than any missing micro-optimization.

Clipping is policy, not an afterthought

A common beginner pattern is “draw first, check later.” On VGA memory that quickly becomes silent corruption. Instead, apply clipping at primitive boundaries before entering the hot loops.

For axis-aligned boxes, clipping is straightforward:

function ClipRect(var X1, Y1, X2, Y2: Integer): Boolean;
begin
  if X1 < 0 then X1 := 0;
  if Y1 < 0 then Y1 := 0;
  if X2 > 319 then X2 := 319;
  if Y2 > 199 then Y2 := 199;
  ClipRect := (X1 <= X2) and (Y1 <= Y2);
end;

Once clipped, your inner loop can stay simple and trustworthy. This is less glamorous than fancy blitters and infinitely more important.

Horizontal fills with reduced state changes

Naive pixel-by-pixel fills set map mask every write. Better approach: process spans in groups where plane mask pattern repeats predictably. Even a modest rework reduces I/O pressure.

procedure HLineX(X1, X2, Y: Integer; C: Byte);
var
  X: Integer;
begin
  if (Y < 0) or (Y > 199) then Exit;
  if X1 > X2 then begin X := X1; X1 := X2; X2 := X; end;
  if X1 < 0 then X1 := 0;
  if X2 > 319 then X2 := 319;

  for X := X1 to X2 do
    PutPixelX(X, Y, C);
end;

This still calls PutPixelX, but with clipping discipline built in. Later you can specialize spans and batch by plane.

Rectangle fills and UI panels

Old DOS interfaces often combine world rendering plus overlays. A clipped rectangle fill is the workhorse for panels, bars, and damage flashes.

procedure FillRectX(X1, Y1, X2, Y2: Integer; C: Byte);
var
  Y: Integer;
begin
  if not ClipRect(X1, Y1, X2, Y2) then Exit;
  for Y := Y1 to Y2 do
    HLineX(X1, X2, Y, C);
end;

It looks boring because good infrastructure often does. Boring primitives are stable primitives.

Line drawing without hidden chaos

For general lines, Bresenham remains practical. The Mode X-specific advice is to keep the stepping algorithm independent from memory layout and delegate write target handling to one consistent pixel primitive.

Why this matters: when bugs appear, you can isolate whether the issue is geometric stepping or planar addressing. Mixed concerns create mixed failures and bad debugging sessions.

Instrument your renderer early

Before moving to sprites, add a diagnostic frame:

draw clipped and unclipped test rectangles at edges
draw diagonal lines through all corners
render page index and frame counter
flash a corner pixel each frame

If this test scene is unstable, your game scene will be chaos with better art.

Structured pass order

A practical frame pipeline in Mode X might be:

clear draw page
draw background spans
draw world primitives
draw sprite layer placeholders
draw HUD rectangles/text
flip display page

This ordering gives deterministic overdraw and clear extension points for Part 3.

Cross-reference with existing DOS workflow

These graphics routines live inside the same operational reality as your boot and tooling discipline:

Old graphics programming is rarely “graphics only.” It is always an ecosystem of memory policy, startup profile, and debugging rhythm.

Next step

Part 3 moves from primitives to actual game-feeling output: masked sprites, palette cycling, and timing control:

Mode X in Turbo Pascal, Part 3: Sprites and Palette Cycling

Primitives are where reliability is born. If your clips are correct and your spans are deterministic, everything built above them gets cheaper to reason about.

One extra practice that helps immediately is recording a tiny “primitive conformance” script in your repo: expected screenshots or checksum-like pixel probes for a fixed test scene. Run it after every renderer change. In retro projects, visual regressions often creep in from seemingly unrelated optimizations, and this one habit catches them early.

Mode X in Turbo Pascal, Part 3: Sprites and Palette Cycling

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

Sprites are where a renderer starts to feel like a game engine. In Mode X, the challenge is not just drawing images quickly. The challenge is managing transparency, overlap order, and visual dynamism while staying within the strict memory and bandwidth constraints of VGA-era hardware.

If your primitives and clipping are not stable yet, go back to Part 2. Sprite bugs are hard enough without foundational uncertainty.

Sprite data strategy: keep it explicit

A reliable sprite pipeline separates three concerns:

Source pixel data.
Optional transparency mask.
Draw routine that respects clipping and planes.

Trying to “infer” transparency from arbitrary colors in ad-hoc code works until assets evolve. Use explicit conventions and document them in your asset converter notes.

Masked blit pattern

A classic masked blit uses one pass to preserve destination where mask says transparent, then overlays sprite pixels where opaque. In Turbo Pascal, even simple byte-level logic remains effective if your loops are predictable.

Pseudo-shape:

for sy := 0 to SpriteH - 1 do
  for sx := 0 to SpriteW - 1 do
    if Mask[sx, sy] <> 0 then
      PutPixelX(DstX + sx, DstY + sy, Sprite[sx, sy]);

You can optimize later with span-based opaque runs. First make it correct under clipping and page boundaries.

Clipping sprites without branching chaos

A practical trick: precompute clipped source and destination windows once per sprite draw call. Then inner loops run branch-light:

srcStartX/srcStartY
srcEndX/srcEndY
dstStartX/dstStartY

This keeps the “should I draw this pixel?” decision out of every iteration and dramatically reduces bug surface.

Draw order as policy

In old-school 2D engines, z-order usually means “draw in sorted sequence.” Keep that sequence explicit:

background
terrain decals
actors
projectiles
effects
HUD

When overlap glitches appear, deterministic order lets you debug with confidence instead of guessing whether timing or memory corruption is involved.

Palette cycling: cheap motion, strong mood

Palette tricks are one of the most useful VGA-era superpowers. Instead of rewriting pixel memory, rotate a subset of palette entries and let existing pixels “animate” automatically. Water shimmer, terminal glow, warning lights, and magic effects become nearly free per frame.

procedure RotatePaletteRange(FirstIdx, LastIdx: Byte);
var
  TmpR, TmpG, TmpB: Byte;
  I: Integer;
begin
  { Assume Palette[] holds RGB triples in 0..63 VGA range }
  TmpR := Palette[LastIdx].R;
  TmpG := Palette[LastIdx].G;
  TmpB := Palette[LastIdx].B;
  for I := LastIdx downto FirstIdx + 1 do
    Palette[I] := Palette[I - 1];
  Palette[FirstIdx].R := TmpR;
  Palette[FirstIdx].G := TmpG;
  Palette[FirstIdx].B := TmpB;
  ApplyPaletteRange(FirstIdx, LastIdx);
end;

The artistic rule is simple: reserve palette bands intentionally. If artists and programmers share the same palette map vocabulary, effects stay predictable.

Timing: lock behavior before optimization

Animation quality depends more on frame pacing than raw speed. Old DOS projects often tied simulation to variable frame rate and then fought phantom bugs for weeks. Better pattern:

fixed simulation tick (e.g., 70 Hz or 60 Hz equivalent)
render as often as practical
interpolate only when necessary

Even on retro hardware, disciplined timing produces smoother perceived motion than occasional fast spikes.

Debug overlays save projects

Add optional overlays you can toggle with a key:

sprite bounding boxes
clip rectangles
page index
tick/frame counters
palette band IDs

These overlays are not “debug clutter.” They are observability for graphics systems that otherwise fail visually without explanation.

Cross references that help this stage

Each one contributes a different layer: memory model, primitive discipline, and workflow habits.

Part 4 moves to tilemaps, camera movement, and data streaming from disk into playable scenes:

Mode X in Turbo Pascal, Part 4: Tilemaps and Streaming

Sprites make a renderer feel alive. Palette cycling makes it feel alive on a budget. Together they are a practical lesson in constraint-driven expressiveness.

If you maintain this code over time, keep a small palette allocation map next to your asset pipeline notes. Which index bands are reserved for UI, which are cycle-safe, which are gameplay-critical. Teams that write this down once avoid months of accidental palette collisions later.

Mode X in Turbo Pascal, Part 4: Tilemaps and Streaming

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

A renderer becomes a game when it can show world-scale structure, not just local effects. That means tilemaps, camera movement, and disciplined data loading. In Mode X-era development, these systems were not optional polish. They were the only way to present rich scenes inside strict memory budgets.

This final Mode X article focuses on operational structure: how to build scenes that scroll smoothly, load predictably, and remain debuggable.

Start with memory budget, not features

Before defining map format, set your memory envelope:

available conventional/extended memory
VRAM page layout
sprite and tile cache size
IO buffer size

Then derive map chunk dimensions from those limits. Teams that reverse the order usually rewrite their map loader halfway through the project.

Tilemap schema that survives growth

A practical map record often includes:

tile index grid (primary layer)
collision flags
optional overlay/effect layer
spawn metadata
trigger markers

Keep versioning in the file header. Old DOS projects often outlived their first map format and paid dearly for “quick binary dumps” with no compatibility markers.

type
  TMapHeader = record
    Magic: array[0..3] of Char;  { 'MAPX' }
    Version: Word;
    Width, Height: Word;         { in tiles }
    TileW, TileH: Byte;
    LayerCount: Byte;
  end;

Version fields are boring until you need to load yesterday’s assets under today’s executable.

Camera math and draw windows

For each frame:

determine camera pixel position
convert to tile-space window
draw only visible tile rectangle plus one-tile margin

The one-tile margin prevents edge pop during sub-tile movement. Combine this with clipped blits from Part 2 and you get stable scrolling without full-map redraw.

Chunked streaming from disk

Large maps should be chunked. Load around camera, evict far chunks, keep hot set warm.

A simple policy works well:

chunk size fixed (for example 32x32 tiles)
maintain 3x3 chunk neighborhood around camera chunk
prefetch movement direction neighbor

This is not overengineering. On slow storage, missing prefetch translates directly into visible hitching.

Keep IO deterministic

Disk access must avoid unpredictable burst behavior during input-critical moments. Two rules help:

schedule loads at known frame points (post-render or pre-update)
cap max bytes read per frame under stress

When a chunk is not ready, prefer visual fallback tile over frame stall. Small visual degradation is often less disruptive than control latency spikes.

Practical cache keys

Use integer chunk coordinates as cache keys. String keys are unnecessary overhead in this environment and complicate diagnostics.

type
  TChunkKey = record
    CX, CY: SmallInt;
  end;

Pair keys with explicit state flags: Absent, Loading, Ready, Dirty. State clarity is more important than clever container choice.

HUD and world composition

Render world layers first, then entities, then HUD into same draw page. Keep HUD draw routines independent from camera transforms. Many old engines leaked camera offsets into UI code and carried that bug tax for years.

You can validate this quickly by forcing camera to extreme coordinates and checking whether UI still anchors correctly.

Failure modes to test intentionally

Test these early, not at content freeze:

camera crossing chunk boundaries repeatedly
high-speed movement through dense trigger zones
partial chunk read failure
map version mismatch
missing tile index fallback path

Each one should degrade gracefully with explicit logging. Silent corruption is far worse than a visible placeholder tile.

Cross references for full pipeline context

These pieces together describe not just rendering, but operation: startup profile, page policy, draw order, and asset logistics.

Closing note on Mode X projects

Mode X is often presented as nostalgic low-level craft. It is also a great systems-design classroom. You learn cache boundaries, streaming policies, deterministic updates, and diagnostic overlays in an environment where consequences are immediate.

If this series worked, you now have a path from first pixel to world-scale scene architecture:

memory model
primitives
sprites and timing
streaming and camera

That sequence is still useful on modern engines. The APIs changed. The discipline did not.

Treat your map format docs as part of runtime code quality. A map pipeline without explicit contracts eventually becomes an incident response problem.

Turbo Pascal Before the Web: The IDE That Trained a Generation

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

Turbo Pascal was more than a compiler. In practice it was a compact school for software engineering, hidden inside a blue screen and distributed on disks you could hold in one hand. Long before tutorials were streamed and before package managers automated everything, Turbo Pascal taught an entire generation how to think about code, failure, and iteration. It did that through constraints, speed, and ruthless clarity.

The first shock for modern developers is startup time. Turbo Pascal did not boot with ceremony. It appeared. You opened the IDE, typed, compiled, and got feedback almost instantly. This changed behavior at a deep level. When feedback loops are short, people experiment. They test tiny ideas. They refactor because trying an alternative costs almost nothing. Slow builds do not just waste minutes; they discourage curiosity. Turbo Pascal accidentally optimized curiosity.

The second shock is the integrated workflow. Editor, compiler, linker, and debugger were not separate worlds stitched together by fragile scripts. They were one coherent environment. Error output was not a scroll of disconnected text; it brought you to the line, in context, immediately. That matters. Good tools reduce the distance between cause and effect. Turbo Pascal reduced that distance aggressively.

Historically, Borland’s positioning was almost subversive. At a time when serious development tools were expensive and often tied to slower workflows, Turbo Pascal arrived fast and comparatively affordable. That democratized real software creation. Hobbyists could ship utilities. Students could build complete projects. Small consultancies could move quickly without enterprise-sized budgets. This was not just a product strategy; it was a distribution of capability.

The language itself also helped. Pascal’s structure encouraged readable programs: explicit blocks, strong typing, and a style that pushed developers toward deliberate design rather than accidental scripts that grew wild. In education, that discipline was gold. In practical DOS development, it reduced whole categories of mistakes that were common in looser environments. People sometimes remember Pascal as “academic,” but in Turbo Pascal form it was deeply practical.

Another underappreciated element was the culture of units. Reusable code packaged in units gave developers a mental model close to modern modular design: separate concerns, publish interfaces, hide implementation details, and reuse tested logic. You felt the architecture, not as a theory chapter, but as something your compiler enforced. If interfaces drifted, builds failed. If dependencies tangled, you noticed immediately. The tool taught architecture by refusing to ignore boundaries.

Debugging was similarly educational. You stepped through code, watched variables, and saw control flow in a way that made program state tangible. On constrained DOS machines, this was not an abstract “observability platform.” It was intimate and local. You learned what your code actually did, not what you hoped it did. That habit scales from small Pascal programs to large distributed systems: inspect state, verify assumptions, narrow uncertainty.

The ecosystem around Turbo Pascal mattered too. Books, magazine listings, BBS uploads, and disk-swapped snippets formed an early social network of practical knowledge. You did not import giant frameworks by default. You copied a unit, read it, understood it, and adapted it. That fostered code literacy. Developers were expected to read source, not just configure dependencies. The result was slower abstraction growth but stronger individual understanding.

Of course, there were trade-offs. DOS memory models were real pain. Hardware diversity meant edge cases. Portability was weaker than today’s expectations. Yet those constraints produced useful engineering habits: explicit resource budgeting, defensive error handling, and careful initialization order. When you had 640K concerns and no rescue layer above you, discipline was not optional.

A subtle historical contribution of Turbo Pascal is that it made tooling aesthetics matter. The environment felt intentional. Keyboard-driven operations, predictable menus, and consistent status information created confidence. Good UI for developers is not cosmetic; it changes throughput and cognitive load. Turbo Pascal proved that decades before “developer experience” became a buzzword.

Why does this still matter? Because many modern teams are relearning the same lessons under different names. We call it “fast feedback,” “inner loop optimization,” “modular design,” “shift-left debugging,” and “operational clarity.” Turbo Pascal users lived these principles daily because the environment rewarded them and punished sloppy alternatives quickly.

If you revisit Turbo Pascal today, don’t treat it as museum nostalgia. Treat it as instrumentation for your own habits. Notice how quickly you can move with fewer layers. Notice how explicit interfaces reduce surprises. Notice how much easier decisions become when tools expose cause and effect immediately. You may not return to DOS workflows, but you will bring back better instincts.

In that sense, Turbo Pascal’s legacy is not a language market share story. It is a craft story. It taught people to build small, test often, structure code, and respect constraints. Those are still the foundations of reliable software, whether your target is a DOS executable, a firmware image, or a cloud service spanning continents.

Turbo Pascal BGI Tutorial: Dynamic Drivers, Linked Drivers, and Diagnostic Harnesses

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

This tutorial gives you a practical BGI workflow that survives deployment:

dynamic driver loading from filesystem
linked-driver strategy for lower runtime dependency risk
a minimal diagnostics harness for startup failures

Preflight: what you need

Turbo Pascal / Borland Pascal environment with Graph unit
one known-good BGI driver set and required .CHR fonts
a test machine/profile where paths are not identical to dev directories

TP5 baseline reminder:

compile needs GRAPH.TPU
runtime needs .BGI drivers
stroked fonts need .CHR files

Step 1: dynamic loading baseline

Create BGITEST.PAS:

program BgiTest;

uses
  Graph, Crt;

var
  gd, gm, gr: Integer;

begin
  gd := Detect;
  InitGraph(gd, gm, '.\BGI');
  gr := GraphResult;
  Writeln('Driver=', gd, ' Mode=', gm, ' GraphResult=', gr);
  if gr <> grOk then
    Halt(1);

  SetColor(15);
  OutTextXY(8, 8, 'BGI OK');
  Rectangle(20, 20, 200, 120);
  ReadKey;
  CloseGraph;
end.

Expected outcome:

with correct path/assets: startup succeeds and simple frame draws
with missing assets: GraphResult indicates error and program exits cleanly

Important TP5 behavior: GraphResult resets to zero after being called. Always store it to a variable once, then evaluate that value.

Path behavior detail: if InitGraph(..., PathToDriver) gets an empty path, the driver files must be in the current directory.

Step 2: deployment discipline for dynamic model

Package checklist:

executable
all required .BGI files for target adapters
all required .CHR fonts
documented runtime path policy

Most “BGI bugs” are missing files or wrong path assumptions.

Step 3: linked-driver strategy (when you need robustness)

Some Borland-era setups support converting/linking BGI driver binaries into object modules and registering them before InitGraph (for example through RegisterBGIdriver and related registration APIs).

General workflow:

run BINOBJ on .BGI file(s) to get .OBJ
link .OBJ file(s) into program
call RegisterBGIdriver before InitGraph
call InitGraph and verify GraphResult

Why teams did this:

fewer runtime file dependencies
simpler deployment to constrained/chaotic DOS installations

Tradeoff:

larger executable and tighter build coupling

Ordering constraint from TP5 docs: calling RegisterBGIdriver after graphics are already active yields grError (-11).

If you use InstallUserDriver with an autodetect callback, TP5 expects that callback to be a FAR-call function with no parameters returning an integer mode or grError.

Step 4: diagnostics harness you should keep forever

Keep a dedicated harness separate from game/app engine:

prints detected driver/mode and GraphResult
renders one line, one rectangle, one text string
exits on keypress

This lets you quickly answer: “is graphics stack alive?” before debugging your full renderer.

Add one negative test here too: intentionally pass wrong mode for a known driver and verify expected grInvalidMode (-10).

Step 5: test matrix (predict first, then run)

Define expected outcomes before running each case:

correct BGI path
missing driver file
missing font file
wrong current directory
TSR-heavy memory profile

For each case, record:

startup status
exact error code/output
whether fallback path triggers correctly

Recommended TP5 error codes to classify in logs:

grNotDetected (-2)
grFileNotFound (-3)
grInvalidDriver (-4)
grNoLoadMem (-5)
grFontNotFound (-8)
grNoFontMem (-9)
grInvalidMode (-10)

Step 6: fallback policy for production-ish DOS apps

Never rely on detect-only logic without fallback:

try preferred mode
fallback to known-safe mode
print actionable error if both fail

A black screen is a product bug, even in retro projects.

About creating custom BGI drivers

Writing full custom BGI drivers is advanced and depends on ABI/tooling details that are often version-specific and poorly documented. Practical teams usually ship stock drivers (dynamic or linked) unless there is a hard requirement for new hardware support.

If you must go custom, treat it as a separate reverse-engineering project with its own test harnesses and compatibility matrix.

Integration notes with overlays and memory strategy

If graphics startup becomes unstable after enabling overlays:

verify overlay initialization order
verify memory headroom before InitGraph
test graphics harness independently from overlayed application paths

This avoids mixing two failure domains during triage.

Memory interaction note from TP5 docs:

Graph allocates heap memory for graphics buffer/driver/font paths
OvrSetBuf also reshapes memory by shrinking heap
call order matters (OvrSetBuf before InitGraph when both are used)

Related reading:

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 Overlay Tutorial: Build, Package, and Debug an OVR Application

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

This tutorial is intentionally practical. You will build a small Turbo Pascal program with one resident path and one overlayed path, then test deployment and failure behavior.

If your install names/options differ, keep the process and adapt the exact menu or command names.

Goal and expected outcomes

Goal: move a cold code path out of always-resident memory and verify it loads on demand from .OVR.

Expected outcomes before you start:

build output includes both .EXE and .OVR
startup succeeds only when overlay initialization succeeds
cold feature call has first-hit latency and warm-hit improvement
removing .OVR produces controlled error path, not random crash

Minimal project layout

OVRDEMO/
  MAIN.PAS
  REPORTS.PAS
  BUILD.BAT

Step 1: write resident core and cold module

REPORTS.PAS (cold path candidate):

{$O+}  { TP5 requirement: unit may be overlaid }
{$F+}  { TP5 requirement for safe calls in overlaid programs }
unit Reports;

interface
procedure RunMonthlyReport;

implementation

procedure RunMonthlyReport;
var
  I: Integer;
  S: LongInt;
begin
  S := 0;
  for I := 1 to 25000 do
    S := S + I;
end;

end.

MAIN.PAS:

program OvrDemo;
{$F+}  { TP5: use FAR call model in non-overlaid code as well }
{$O+}  { keep overlay directives enabled in this module }

uses
  Overlay, Crt, Dos, Reports;
{$O Reports}  { select this used unit for overlay linking }

var
  Ch: Char;
  ExeDir, ExeName, ExeExt: PathStr;
  OvrFile: PathStr;

procedure InitOverlays;
begin
  FSplit(ParamStr(0), ExeDir, ExeName, ExeExt);
  OvrFile := ExeDir + ExeName + '.OVR';
  OvrInit(OvrFile);
  if OvrResult <> ovrOk then
  begin
    Writeln('Overlay init failed for ', OvrFile, ', code=', OvrResult);
    Halt(1);
  end;
  OvrSetBuf(60000);
end;

begin
  InitOverlays;
  Writeln('Press R to run report, ESC to exit');
  repeat
    Ch := ReadKey;
    case UpCase(Ch) of
      'R':
        begin
          Writeln('Running report...');
          RunMonthlyReport;
          Writeln('Done.');
        end;
    end;
  until Ch = #27;
end.

Step 2: enable overlay policy

Overlay output is not triggered by uses Overlay alone. You need both:

mark unit as overlay-eligible at compile time
select unit for overlaying from the main program

For Turbo Pascal 5.0 (per Reference Guide), these are hard rules:

all overlaid units must be compiled with {$O+}
active call chain must use FAR call model in overlaid programs
practical safe pattern: {$O+,F+} in overlaid units, {$F+} in other units and main
{$O UnitName} must appear after uses
uses must name Overlay before any overlaid unit
build must be to disk (not memory)

The full REPORTS.PAS and MAIN.PAS examples above include these directives directly.

Why `{$O+}` exists (TP5 technical reason)

In TP5, {$O+} is not just a “permission bit” for overlaying. It also changes code generation for calls between overlaid units to keep parameter pointers safe.

Classic hazard:

caller unit passes pointer to a code-segment-based constant (for example a string/set constant)
callee is in another overlaid unit
overlay swap can overwrite caller code segment region
raw pointer becomes invalid

TP5 {$O+}-aware code generation mitigates this by copying such constants into stack temporaries before passing pointers in overlaid-to-overlaid scenarios.

Typical source-level shape:

In REPORTS.PAS:

{$O+}  { TP5 mandatory for overlaid units }
{$F+}  { TP5 FAR-call requirement }
unit Reports;
...

In MAIN.PAS:

program OvrDemo;
uses Overlay, Crt, Dos, Reports;
{$O Reports}  { overlay unit-name directive: mark Reports for overlay link }

Without the unit-name selection ({$O Reports} or equivalent IDE setting), the unit can stay fully linked into the EXE even if {$O+} is present.

TP5 constraint from the same documentation set: among standard units, only Dos is overlayable; System, Overlay, Crt, Graph, Turbo3, and Graph3 cannot be overlaid.

Step 2.5: when the `.OVR` file is actually created

This is the key technical point that is often misunderstood:

REPORTS.PAS compiles to REPORTS.TPU (unit artifact).
MAIN.PAS is compiled and then linked with all used units.
During link, overlay-managed code is split out and written to one overlay file.

So .OVR is a link-time output, not a unit-compile output.

How code is selected into `.OVR`

Selection is not by “file extension magic” and not by uses Overlay. The link pipeline does this:

mark used code blocks from reachable entry points
check units marked for overlaying (via overlay unit-name directive/options)
for callable routines in those units, emit call stubs in EXE and write overlayed code blocks to .OVR

So:

unused routines can be omitted entirely
selected routines from one or more units can end up in the same .OVR
unit selection is explicit, routine placement is linker-driven from that set

Naming rule

The overlay file is tied to the final executable base name, not to a single unit.

compile/link target MAIN.EXE -> overlay file MAIN.OVR
compile/link target APP.EXE -> overlay file APP.OVR

It is not REPORTS.OVR just because Reports contains overlayed routines. One executable can include overlayed code from multiple units, and they are packed into that executable’s single overlay payload.

When `.OVR` may not appear

If no code is actually emitted as overlayed in the final link result, no .OVR file is produced. In that case, check project options/directives first.

Step 3: build and verify artifacts

Build with your normal tool path (IDE or CLI). After successful build:

verify your output executable exists (for example MAIN.EXE if compiling MAIN.PAS)
verify matching overlay file exists with the same base name (for example MAIN.OVR)
record file sizes and timestamp

If .OVR is missing, your overlay profile is not active.

Step 4: runtime tests

Test A - healthy run

Expected:

startup prints no overlay error
first R call may be slower
repeated R calls are often faster (buffer reuse)

Test B - missing OVR

Temporarily rename the generated overlay file (for example MAIN.OVR).

Expected:

startup exits with explicit overlay init error
no undefined behavior

If it crashes instead, fix error handling before continuing.

Step 4.5: initialization variants (`OvrInit`, `OvrInitEMS`, `OvrSetBuf`)

Minimal initialization:

OvrInit(OvrFile);

If initialization fails and you still call an overlaid routine, TP5 behavior is runtime failure (the reference guide calls out runtime error 208).

OvrInit practical lookup behavior (TP5): if OvrFile has no drive/path, the manager searches current directory, then EXE directory (DOS 3.x), then PATH.

OvrInit result handling (OvrResult):

ovrOk: initialized
ovrNotFound: overlay file not found
ovrError: invalid overlay format or program has no overlays

EMS-assisted initialization:

OvrInit(OvrFile);
OvrInitEMS;

OvrInitEMS can move overlay backing storage to EMS (when available), but execution still requires copying overlays into the normal-memory overlay buffer.

OvrInitEMS result handling (OvrResult):

ovrOk: overlays loaded into EMS
ovrIOError: read error while loading overlay file
ovrNoEMSDriver: no EMS driver detected
ovrNoEMSMemory: insufficient free EMS

On OvrInitEMS errors, overlay manager still runs from disk-backed loading.

Buffer sizing:

TP5 starts with a minimal overlay buffer (large enough for largest overlay).
For cross-calling overlay groups, this can cause excessive swapping.
OvrSetBuf increases buffer by shrinking heap.
legal range (TP5): BufSize >= initial and BufSize <= MemAvail + OvrGetBuf
if you increase buffer, adjust {$M ...} heap minimum accordingly

Important ordering rule (TP5): call OvrSetBuf while heap is effectively empty. If using Graph, call OvrSetBuf before InitGraph, because InitGraph allocates heap memory and can prevent buffer growth.

Step 5: tune overlay buffer with measurement

Run the same interaction script while changing OvrSetBuf:

small buffer (for example 16K)
medium buffer (for example 32K)
larger buffer (for example 60K)

Expected pattern:

too small: frequent reload stalls
too large: less stall, but memory pressure elsewhere

Choose by measured latency and memory headroom, not by guess.

Step 6: boundary correction when overlay thrashes

If one action triggers repeated slowdowns:

move shared helpers from overlay unit to resident unit
keep deep cold logic in overlay unit
reduce cross-calls between overlay units

Overlay design is call-graph design.

Troubleshooting matrix

Symptom: unresolved symbol at link

check unit/object participation in link graph
check far/near and declaration compatibility

Symptom: startup overlay error

check .OVR filename/path assumptions
check deployment directory, not just dev directory

Symptom: intermittent slowdown

profile call path for overlay churn
increase buffer or move hot helpers resident

What this tutorial teaches beyond overlays

You practice four skills that transfer everywhere:

define expected behavior before test
verify artifact set before runtime
isolate runtime dependencies explicitly
tune with measured data, not assumptions

Related reading:

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 4: Graphics Drivers, BGI, and Rendering Integration

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

Turbo Pascal graphics was never just “call Graph and draw.” In production-ish DOS projects, graphics was an asset pipeline problem, a deployment problem, and a diagnostics problem at least as much as an API problem.

This part focuses on BGI driver mechanics, practical packaging, and the exact checks that separate real faults from folklore.

Structure map: BGI architecture and operational models → Graph unit runtime contracts and GraphResult handling → dynamic vs linked drivers, packaging and pitfalls → font/driver matrix and memory interactions → BGI artifacts in build and deploy pipelines → debugging rendering failures on real DOS → team checklists and release hardening.

BGI architecture in practical terms

The Graph unit provides the API. Under it, runtime driver/font assets do the hardware-specific work. The unit itself is statically linked; it does not contain adapter-specific code. Instead, it loads a driver binary that knows how to program the hardware (CGA, EGA, VGA, Hercules, etc.) and interpret high-level drawing calls. Fonts are separate assets because they are large and optional — you only load the ones your UI needs.

driver assets: usually .BGI (e.g. EGAVGA.BGI, CGA.BGI)
font assets: .CHR stroked fonts (e.g. TRIP.CHR, GOTH.CHR)
initialization: InitGraph(driver, mode, path)
status reporting: GraphResult
cleanup: CloseGraph

Two operational models exist:

Dynamic runtime loading from filesystem path — driver and font files are read from disk at InitGraph time.
Linked-driver — driver (and optionally font) binaries converted to .OBJ and linked into the executable; registration APIs make them available before InitGraph.

Both are valid. Pick by deployment constraints: dynamic keeps builds small and simple but requires correct runtime paths; linked reduces file dependencies and installer mistakes at the cost of executable size and build coupling. Many teams shipped dynamic for development and internal testing, then produced a linked-driver build for floppy or constrained deployments where users were unlikely to preserve directory structure correctly.

Graph unit runtime contracts and GraphResult handling

Every Graph operation that can fail updates an internal error code. GraphResult returns that code and, in TP5, resets it to zero on read. That one-read semantic causes subtle bugs when code checks GraphResult multiple times or assumes it remains set across calls.

Contract rules:

Call GraphResult once after any operation that may fail, store the value in a local variable, then branch on that variable.
Do not assume GraphResult stays non-zero until the next failed operation.
Never call GraphResult before the operation you intend to check — earlier successful operations clear it.

{ WRONG: second check sees zero from first read }
InitGraph(gd, gm, '.\BGI');
if GraphResult <> grOk then Halt(1);
if GraphResult <> grOk then ...   { always passes; result was cleared }

{ RIGHT: single read, then use stored value }
InitGraph(gd, gm, '.\BGI');
gr := GraphResult;
if gr <> grOk then
  begin
    Writeln('Init failed: ', gr);
    Halt(1);
  end;

TP5 error codes worth memorizing for triage:

Code	Constant	Typical cause
0	`grOk`	Success
-1	`grNoInitGraph`	Graphics not initialized
-2	`grNotDetected`	No compatible adapter found
-3	`grFileNotFound`	Driver or font file missing on path
-4	`grInvalidDriver`	Driver format invalid or mismatched
-5	`grNoLoadMem`	Not enough heap for driver/buffer
-8	`grFontNotFound`	Font file missing
-9	`grNoFontMem`	Not enough heap for font
-10	`grInvalidMode`	Mode not supported by driver
-11	`grError`	General error; often registration/order violation

When grNoLoadMem appears, suspect overlay buffer sizing or TSR load order before blaming hardware. When grFileNotFound appears, verify PathToDriver resolves from the process’s current directory, not the source tree. Some TP/BP variants may use PathStr or environment variables for default paths; the TP5 reference is explicit that an empty path means current directory, and documentation for later versions should be consulted if behavior differs.

Uncertainty note: Exact GraphResult semantics and numeric codes can vary slightly between TP5, TP6, TP7, and BP7. The table above reflects TP5 reference values; when targeting multiple versions, confirm codes in your toolchain’s GRAPH.TPU or include files.

TP5 baseline facts from the reference guide

For Turbo Pascal 5.0, the reference guide is explicit:

compile-time dependency: GRAPH.TPU
runtime dependency: one or more .BGI drivers
if stroked fonts are used: one or more .CHR files

InitGraph loads the selected driver and enters graphics mode. CloseGraph unloads/restores previous mode. This is the lifecycle baseline. After CloseGraph, you may re-enter graphics mode with another InitGraph call, but driver and font state are reset; any registered user drivers must be re-registered if you use the linked model.

Dynamic model: fastest to start, easiest to break in deployment

uses Graph;
var
  gd, gm, gr: Integer;
begin
  gd := Detect;
  InitGraph(gd, gm, 'C:\APP\BGI');
  gr := GraphResult;
  if gr <> grOk then
    begin
      Writeln('BGI init failed: ', gr);
      Halt(1);
    end;
  { render }
  CloseGraph;
end.

Expected outcome:

works immediately in dev environment with full BGI directory
fails fast if path/assets are missing, with actionable error code

Common failure is not code. It is wrong path assumptions after installation. Typical mistakes: hardcoding C:\TP\BGI or .\BGI when the app runs from A:\ or a network drive; assuming GetDir equals executable directory; using forward slashes on systems that expect backslashes.

TP5 path behavior: if PathToDriver is empty, driver files must be in the current directory. If you pass a path, it must end with a trailing backslash on some implementations to be treated as a directory. Conservative practice: always pass an explicit path built from ParamStr(0) or GetDir, and ensure it ends with \.

Path resolution example:

uses Dos, Graph;
var
  ExeDir, BgiPath: PathStr;
  Name, Ext: PathStr;
begin
  FSplit(ParamStr(0), ExeDir, Name, Ext);
  BgiPath := ExeDir + 'BGI' + '\';
  InitGraph(gd, gm, BgiPath);
  gr := GraphResult;
  ...
end.

This assumes BGI is a subdirectory next to the executable. If you ship with BGI alongside .EXE, this pattern works regardless of where the user installed the app.

Triage for dynamic-load failures:

Run the diagnostic harness (see below) from the same directory and path the app will use in production.
If harness works but app fails, compare paths and current-directory assumptions between harness and app.
If grFileNotFound: list directory contents, verify file names match exactly (case may matter on some setups).
If grNoLoadMem: reduce overlay buffer, close TSRs, or switch to linked driver.

Linked-driver model: more robust runtime, tighter build coupling

Some Borland-era toolchains support converting/linking driver binaries into object form and registering them at startup (for example via RegisterBGIdriver and companion font registration APIs). This avoids runtime dependency on external .BGI files but increases binary size and build complexity.

Practical pattern:

convert/select driver object module
link object into project ({$L ...} or linker config)
register driver before InitGraph
call InitGraph with empty or local path expectations

Exact symbol names and conversion utilities depend on installation/profile, so document your specific toolchain once and keep it version-pinned.

TP5 manual flow for linked drivers is concrete:

convert .BGI to .OBJ with BINOBJ
link resulting .OBJ into the executable
call RegisterBGIdriver before InitGraph

If you call RegisterBGIdriver after graphics are already active, TP5 reports grError (-11). Same rule applies to RegisterBGIfont: register before first use of that font.

BINOBJ invocation (exact syntax varies by Borland install):

`1`	`BINOBJ EGAVGA.BGI EGAVGA EGAVGA`

This produces EGAVGA.OBJ with symbols for the binary blob. The linker then pulls it in via {$L EGAVGA.OBJ}. The two symbol names after the filename are typically the public name and the segment/object name; consult your BINOBJ documentation. After conversion, add the .OBJ to your build and ensure it is linked before the unit that calls RegisterBGIdriver. If the symbol is undefined at link time, the .OBJ was not included or the declaration does not match BINOBJ output.

Illustrative registration shape (symbol names vary by conversion/tooling):

{$L EGAVGA.OBJ}

procedure RegisterEgaVga; external;

begin
  RegisterBGIdriver(@RegisterEgaVga);
  { or InstallUserDriver + callback, depending on toolchain }
  InitGraph(gd, gm, '');
  gr := GraphResult;
  if gr <> grOk then Halt(1);
  { ... }
end.

Treat symbol names as toolchain-specific; BINOBJ output and TP/BP docs define the exact entry. If registration order is wrong, you get grError with no obvious message — add logging before each Graph call during integration.

Pitfalls: Forgetting to register before InitGraph; registering after InitGraph; linking the wrong driver .OBJ for the target adapter; mixing driver versions (e.g. TP5 vs BP7) when BGI format differs. Another pitfall: assuming Detect returns the same driver on all VGA systems. Some VGA clones or BIOS quirks can cause Detect to fail or return a conservative mode; hardcoding a fallback (e.g. if gd = Detect then gd := VGA; gm := VGAHi) can improve robustness when autodetect is unreliable. When linking multiple drivers (e.g. VGA + CGA fallback), register all before InitGraph; the order may matter for some toolchains — consult your Graph unit docs. A linked build that works in the IDE can fail at standalone run if the .OBJ was not linked or the external symbol name does not match BINOBJ output; add a build step that verifies the linked executable size increased by the expected driver blob size.

Asset set discipline (driver + font matrix)

For each shipping mode profile, define and freeze:

required driver files (e.g. EGAVGA.BGI for VGA, CGA.BGI for CGA fallback)
required font files (e.g. TRIP.CHR, GOTH.CHR if SetTextStyle uses them)
fallback mode behavior (what mode to try if Detect fails or preferred mode unavailable)
startup diagnostics text (what to print on failure)

Without this matrix, BGI deployment drifts silently between machines. One developer ships with EGAVGA.BGI only; another’s machine has CGA.BGI in path; field reports “black screen” and nobody knows which adapter or driver set was used.

Driver and font packaging rules: Drivers and fonts must be version-pinned to the toolchain that produced GRAPH.TPU. TP5 EGAVGA.BGI is not guaranteed compatible with BP7’s Graph unit; format and entry-point layout can differ. Package drivers as a locked set: document “EGAVGA.BGI from TP5.0 install dated 1989” in your release notes. Fonts are similarly sensitive: a .CHR from one toolchain may load but render incorrectly with another. When upgrading the compiler, re-validate the full driver+font matrix against your harness before cutting a release. Include file sizes and checksums in the manifest so swapped or corrupted copies are detectable.

Font/driver matrix discipline: Not all fonts work with all drivers. Stroked fonts (.CHR) are driver-independent in principle, but SetTextStyle calls before a font is loaded fall back to default. Document which fonts are required for each UI path. If you use InstallUserFont or RegisterBGIfont, the registration order and timing must match the matrix — register before any SetTextStyle that selects that font. A minimal matrix might look like:

Target adapter	Driver	Fonts used	Fallback mode
VGA	EGAVGA.BGI	TRIP, GOTH	VGAHi
EGA	EGAVGA.BGI	TRIP	EGALo
CGA	CGA.BGI	(default)	CGAC0

Ship only drivers and fonts listed for your supported targets. Including extra files “just in case” increases install size and the chance of path confusion. Update the matrix when adding support for new adapters (e.g. Hercules, MCGA) or when dropping support for legacy hardware.

BGI artifacts in build and deploy pipelines

BGI assets are build outputs as much as runtime dependencies. Include them in your artifact pipeline so releases are reproducible.

Package layout:

RELEASE/
  MYAPP.EXE
  BGI/
    EGAVGA.BGI
    CGA.BGI
  FONTS/
    TRIP.CHR
    GOTH.CHR
  README.TXT

If using linked drivers, BGI/ and FONTS/ may be empty, but the layout should still be documented so installers know what to expect.

Build script integration:

@echo off
set BGI_SRC=C:\TP\BGI
set BGI_OUT=..\RELEASE\BGI
if not exist %BGI_OUT% mkdir %BGI_OUT%
copy %BGI_SRC%\EGAVGA.BGI %BGI_OUT%\
copy %BGI_SRC%\CGA.BGI %BGI_OUT%\
if not exist ..\RELEASE\FONTS mkdir ..\RELEASE\FONTS
copy %BGI_SRC%\TRIP.CHR ..\RELEASE\FONTS\
rem checksum for release manifest
... checksum tool ...

Run the diagnostic harness as a post-build step: execute it from RELEASE\ with BGI as subdirectory and assert GraphResult = grOk. If the harness fails in clean build output, fix paths before shipping. Some teams wired the harness as BUILD.BAT final step with if errorlevel 1 to fail the build.

Checksum discipline: Store MD5 or CRC of each .BGI and .CHR in a manifest. When field reports “weird corruption” or mode errors, compare checksums to rule out truncated or swapped files. A swapped CGA.BGI and EGAVGA.BGI (e.g. misnamed copies) produces grInvalidDriver or garbled output; checksums catch that quickly. Run checksum verification as part of the build pipeline: after copying assets to RELEASE\, compute checksums and append to a MANIFEST.TXT; archive that manifest with the release. During support triage, ask the user to run a simple checksum tool (or provide a tiny .COM that prints file sizes) and compare against the manifest — mismatches point to installer bugs, disk errors, or manual file replacements.

Floppy and installer considerations: If distributing on floppies, put MYAPP.EXE on disk 1 and BGI\ contents on the same or next disk. Installer scripts should copy BGI\ into the target directory and set current-directory expectations in a README. Avoid assuming users will run from a subdirectory; many double-click or type MYAPP from C:\GAMES\ and expect .\BGI to mean C:\GAMES\BGI.

Are BGI file formats fully documented?

Honest answer: not in a stable, complete way that is safe to treat as universal across all TP/BP-era variants. You can inspect BGI bytes and infer structure, but production workflows historically relied on Borland-provided drivers and APIs, not custom byte-level authoring from scratch. Third-party efforts (e.g. SDL_bgi, Free Pascal Graph unit) have reverse-engineered portions of the format for compatibility; those sources may help if you need to validate or debug driver files, but do not assume full specification coverage.

What you can reliably do today:

verify driver/font assets exist and match expected set
checksum assets as release artifacts
use diagnostic harnesses to confirm runtime load path

Diagnostics pitfall: Do not assume a BGI file is valid just because it exists. A truncated or corrupted file can produce grInvalidDriver or unpredictable behavior. If you suspect file integrity, compare size and checksum against a known-good copy from your toolchain installation.

“How are BGI drivers created?” practical answer

Three realistic paths:

Use stock Borland drivers (most common historical path). Ship EGAVGA.BGI, CGA.BGI, etc. from your TP/BP installation. Ensure version consistency: TP5 drivers are not guaranteed compatible with BP7 Graph unit and vice versa. When in doubt, use drivers from the same toolchain that produced GRAPH.TPU.
Link stock drivers into executable for deployment robustness. Convert with BINOBJ, link, register. Same version-pinning rule applies.
Author custom driver only if you own/understand ABI details and tooling. The BGI format includes device-specific entry points, mode tables, and drawing primitives. Third-party documentation (e.g. from replacement BGI projects) exists but varies in accuracy. Treat custom drivers as a separate maintenance burden.

Path 3 is advanced reverse-engineering/ABI work. It is possible, but not the right default for project delivery unless driver capabilities are missing.

BGI startup diagnostics harness (must-have)

program BgiDiag;
uses Graph, Crt;
var
  gd, gm, gr: Integer;
begin
  gd := Detect;
  InitGraph(gd, gm, '.\BGI');
  gr := GraphResult;
  Writeln('Driver=', gd, ' Mode=', gm, ' GraphResult=', gr);
  if gr = grOk then
  begin
    SetColor(15);
    OutTextXY(8, 8, 'BGI init OK');
    Line(0, 0, GetMaxX, GetMaxY);
    ReadKey;
    CloseGraph;
  end
  else
    Writeln('Init failed. Check path, files, memory.');
end.

Run this before debugging your game engine. It isolates path/driver faults from rendering logic faults. Keep it as a separate program in your tree; do not embed it inside the main app, because you want to run it in isolation when the full app crashes before any output. A harness that runs to completion proves the BGI stack works; if the harness fails, fix that before debugging renderer code. Extend the harness when you encounter new failure modes: add a font-load test if grFontNotFound appears in the field, or a Detect-then- forced-mode variant if adapter detection is unreliable. The harness becomes your regression suite for the BGI layer; document each variant and when to run it. Some teams maintained a BGIDIAG.EXE in the release package so support could ask users to run it and report the printed codes — a single number (GraphResult) often suffices to distinguish path, memory, and driver issues without requiring logs or repro steps.

Triage procedure with the harness:

Run from project root with .\BGI containing drivers — expect grOk.
Run from same directory but rename BGI to BGI_BACKUP — expect grFileNotFound; confirm printed code matches.
Run from a directory without BGI subfolder — expect grFileNotFound.
On a TSR-heavy config (mouse, network driver, etc.), run harness — if grNoLoadMem, document minimum free conventional memory for your build.

Important TP5 behavior: GraphResult resets to zero after it has been called. Store it in a variable once and evaluate that variable.

Font handling is a real subsystem

If UI layout depends on font metrics, .CHR assets are first-class artifacts:

version and checksum them
package with same discipline as executables
test fallback behavior explicitly

Silent fallback to default font can break coordinates, clipping, and hit zones. A menu rendered with GOTH.CHR has different line heights than the default; if the font fails to load, text may overlap or clip incorrectly.

TP5 adds two separate extension points:

InstallUserFont (register by name/file path)
RegisterBGIfont (register loaded or linked-in font pointer)

As with drivers, registration must be done before normal graphics workflow relies on those resources. After SetTextStyle(...), check GraphResult if the font was user-installed; grFontNotFound or grNoFontMem indicate load failure.

Memory interaction: Stroked fonts are loaded into heap. A large .CHR plus graphics buffer plus overlay buffer can exhaust conventional memory. If grNoFontMem appears only with certain fonts, try smaller fonts or linked-font approach for the critical path. Font packaging parallels driver packaging: ship only the fonts your UI actually uses, version-pin them to your toolchain, and include checksums in the release manifest. A common mistake is bundling every .CHR from the TP install “for completeness” — this bloats the package and increases the chance of loading the wrong font by typo or path confusion. If SetTextStyle references a font that was never loaded or registered, the unit falls back to default; the fallback is silent, so layout assumptions (lower height, different metrics) can break. Add an explicit font-load check after SetTextStyle for user fonts and log GraphResult during development.

BGI + overlays + memory budget interaction

Graphics initialization and overlays interact with memory pressure. If startup becomes unstable after enabling overlays or TSR-heavy profiles, validate:

available memory headroom before InitGraph
overlay manager buffer size (OvrSetBuf)
order of subsystem initialization

Treat graphics bugs and memory bugs as potentially coupled until proven otherwise. Memory interplay with overlays is the most common source of “works in dev, fails in release” BGI bugs: the overlay manager allocates a contiguous buffer from the heap; Graph allocates its own buffers from the same heap. If the overlay buffer is carved out first, Graph gets what remains; if Graph allocates first and overlays later try to grow, the heap can be fragmented or exhausted. grNoLoadMem often appears when overlay and Graph compete for the same pool without a clear initialization order.

TP5 memory detail: Graph uses heap for graphics buffer, loaded drivers, and loaded stroked fonts (unless linked/registered path is used). This is why overlay buffer sizing (OvrSetBuf) and InitGraph order can conflict.

Order rule: Call OvrSetBuf (and OvrInit) before InitGraph. The overlay manager carves its buffer from the heap; Graph then allocates from what remains. Reversing the order can leave insufficient room for either. A typical failure: InitGraph succeeds, then OvrSetBuf shrinks the heap, and a later overlay load or Graph operation fails with grNoLoadMem or overlay error. The fix is to establish overlay buffer first, then let Graph allocate from the remaining free memory.

OvrInit(OvrFile);
if OvrResult <> ovrOk then Halt(1);
OvrSetBuf(50000);     { before InitGraph }
InitGraph(gd, gm, '.\BGI');
gr := GraphResult;

Memory budgeting: On a 640 KB DOS machine, TSRs and DOS typically consume 50–150 KB. Your app gets the rest. A VGA buffer (640×480×1 byte) is ~300 KB; EGAVGA.BGI adds tens of KB when loaded; stroked fonts add more. If you use overlays, their buffer comes from the same pool. Document a minimum free-memory requirement (e.g. “400 KB free conventional memory”) and test at that threshold. Boot with a minimal CONFIG.SYS and AUTOEXEC.BAT to simulate a memory-tight environment; if your app runs there, it will usually run on richer systems. This simple test catches many “works on my machine” deployment failures.

Overlay–Graph allocation interplay: The heap layout after OvrSetBuf and InitGraph is toolchain- and order-dependent. A rough rule of thumb: VGA graphics buffer (~300 KB) + EGAVGA driver (~30–50 KB when loaded) + one stroked font (~20–40 KB) leaves little for overlays on a 640 KB system with 400 KB free. If you use both overlays and Graph, establish the overlay buffer first with a conservative size, then init Graph; measure free memory before and after each step during integration. Some teams added a startup banner (“Free mem: XXXXX”) before InitGraph to catch regressions. Uncertainty note: Exact allocation order and sizes can vary between TP5, TP6, and BP7; when in doubt, instrument and measure on your target configuration.

Debugging rendering failures on real DOS systems

When graphics fail in the field but work in development, systematic triage narrows the cause. Use a rendering triage loop: run the diagnostic harness first; if it passes, the fault is in application rendering logic or asset loading, not BGI init. If the harness fails, iterate on path, memory, or driver until it passes, then return to the full app. Do not debug a complex renderer while BGI fundamentals are still failing — you will waste time chasing symptoms (e.g. “Line draws wrong”) that stem from an earlier init or mode problem.

Release verification on real hardware: Before signing off a build, run the full checklist on at least one physical DOS machine (or a well-configured emulator that matches period behavior). Boot from floppy or minimal HD; run from A:\, C:\GAMES, and a nested subdirectory; try with and without common TSRs (mouse, sound driver). Known problematic configurations include: VGA clones with nonstandard BIOS mode tables, EGA systems with 256 KB vs 64 KB variants, and machines with < 400 KB free conventional memory. Document which adapter and memory profile you verified; when field reports arrive, compare against that baseline. A build that has never been run on real hardware is a risk.

Triage steps:

Black screen, no message: Program may be exiting before any output. Add a Writeln('Starting...') before InitGraph; if it never appears, the crash is earlier (e.g. overlay init, missing .OVR). On some DOS configurations, mode switch can also blank the screen before text output is visible; redirect output to a file (MYAPP > LOG.TXT 2>&1) to confirm whether any text was produced.
Black screen, message appeared then vanished: Mode switch may have failed, or the program exited immediately. Ensure GraphResult is checked and stored before any cleanup; add ReadKey or Delay before CloseGraph in harness to confirm. If the message flashes too quickly to read, write it to a file as well.
Wrong resolution or garbled display: Driver/mode mismatch. Detect may pick a different mode on different adapters; log gd and gm and compare to adapter documentation. Force a known mode (e.g. gd := VGA; gm := VGAHi) for compatibility testing.
Works once, fails on second run: TSR or environment pollution. Reboot to clean state; disable TSRs one by one. Some drivers leave video state inconsistent after CloseGraph.
grNoLoadMem on target only: Conventional memory too low. Run MEM before app; compare to dev machine. Reduce overlay buffer or ship linked driver build.

Keep a triage log: adapter type, driver set, free memory, TSR list, and exact GraphResult value. Reproducible cases go into the test matrix. When a new symptom appears (e.g. “screen flickers then goes black”), add a minimal reproducer to the harness: if you can trigger it there, debug there; if only the full app exhibits it, the cause is likely in overlay loading order, asset sequencing, or interaction with game/UI logic. This divide-and-conquer approach keeps triage loops short and deterministic.

Team checklists and release hardening

Before release, the team should complete:

Pre-build:

Unit search path, object path, and BGI asset path documented and version-pinned
Build script produces deterministic output (clean build, no stale artifacts)

Build:

All required .BGI and .CHR copied to release layout
Diagnostic harness runs successfully from release directory
Checksums recorded for .EXE, .OVR (if used), .BGI, .CHR

Post-build verification:

Test from directory different from source (e.g. C:\TEST\, A:\)
Intentionally remove one driver, run app — verify error message, no crash
Test with overlay file missing (if applicable) — verify controlled exit
One memory-stressed run (e.g. with MEM reporting < 400 KB free)
Run diagnostic harness from same release layout; assert it reports grOk
If distributing on floppy: boot from disk 1, run from A:\, confirm BGI path resolves correctly (e.g. A:\BGI\ when app is on A:\)

Release package:

README includes BGI path requirements and minimum memory
Build manifest (checksums, compiler version, options) archived with artifacts

Expected outcome: actionable startup message on any failure, never black-screen ambiguity. When a user reports “does not work,” the checklist gives you questions to ask (adapter, path, memory, exact error text) instead of blind guesswork. Teams that shipped without this discipline often spent hours on support calls trying to reproduce “black screen” with no data. A single Writeln('BGI error: ', gr) before Halt(1) can save days of debugging.

Useful TP5 InitGraph failure codes to log:

grNotDetected (-2)
grFileNotFound (-3)
grInvalidDriver (-4)
grNoLoadMem (-5)
grInvalidMode (-10)

Where to go deeper

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

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.

Turbo Pascal Units as Architecture, Not Just Reuse

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

Most people first meet Turbo Pascal units as “how to avoid copy-pasting procedures.” That is true and incomplete. In real projects, units are architecture boundaries. They define what the rest of the system is allowed to know, hide what can change, and make refactoring survivable under pressure.

In constrained DOS projects, this was not academic design purity. It was the difference between shipping and debugging forever.

Interface section is a contract surface

A good unit interface exposes minimal, stable operations. It does not leak storage details, timing internals, or helper routines with unclear ownership. You can read the interface as a capability map.

unit RenderCore;

interface
procedure BeginFrame;
procedure DrawSprite(X, Y, Id: Integer);
procedure EndFrame;

implementation
{ internal page selection, clipping, palette handling }
end.

Notice what is missing: page indices, raw VGA register details, sprite memory layout. Those remain private so callers cannot create illegal states casually.

Separation patterns that work

A practical retro project often benefits from explicit layers:

SysCfg: startup profile, paths, feature flags
Input: keyboard state and edge detection
RenderCore: page lifecycle and primitives
World: simulation and collision
UiHud: overlays independent of camera

Each layer exports what the next layer needs, and no more.

This is still modern architecture wisdom, just with smaller tools.

Compile-time feedback as architecture feedback

One advantage of strong unit boundaries: breakage appears quickly at compile time. If you change a function signature in one interface, all dependent call sites surface immediately. That pressure encourages deliberate changes rather than implicit behavior drift.

When architecture boundaries are vague, breakage tends to become runtime surprises. In DOS-era loops, compile-time certainty was a strategic advantage.

State ownership rules

Global variables are tempting in small projects. They also erase accountability. Better pattern:

each unit owns its state
mutation happens through explicit procedures
read-only queries are exposed as functions

unit FrameClock;

interface
procedure Tick;
function FrameCount: LongInt;

implementation
var
  GFrameCount: LongInt;

procedure Tick;
begin
  Inc(GFrameCount);
end;

function FrameCount: LongInt;
begin
  FrameCount := GFrameCount;
end;
end.

This small discipline scales surprisingly far.

Circular dependencies are architecture warnings

If Unit A needs Unit B and B needs A, the system is signaling a design issue. In Turbo Pascal this becomes obvious quickly because cycles are painful. Use that pain as feedback:

extract shared abstractions into Unit C
invert direction of calls through callback interfaces
move policy decisions up a layer

The language/tooling friction nudges you toward cleaner dependency graphs.

Testing mindset without modern frameworks

Even without a test framework, you can create deterministic validation by small harness units:

fixture setup procedure
operation call
assertion-like result check
text output summary

The key is isolating seams through interfaces. If a rendering unit can be called with prepared buffers and predictable state, manual regression checks become cheap and reliable.

Architecture and performance are not enemies

Some developers fear unit boundaries will cost speed. In most DOS-scale projects, the bigger performance wins come from algorithm choice and memory locality, not from collapsing all code into one monolith. Clear units help you identify hot paths accurately and optimize where it matters.

For example, keeping low-level pixel paths inside RenderCore makes targeted optimization straightforward while preserving clean call sites elsewhere.

Cross references in this project

These articles show the same pattern from different angles:

Different domains, same operational truth: explicit boundaries reduce failure ambiguity.

A migration strategy for messy codebases

If you already have a tangled Pascal codebase, do not rewrite everything. Do staged extraction:

identify one unstable subsystem
define minimal interface for it
move internals behind unit boundary
replace direct global access with explicit calls
repeat for next subsystem

This approach keeps software running while architecture improves incrementally.

Turbo Pascal units are sometimes framed as nostalgic language features. They are better understood as practical architecture tools with excellent signal-to-noise ratio. Under constraints, that ratio is everything.

Writing Turbo Pascal in 2025

Sun, 19 Oct 2025 00:00:00 +0000

Turbo Pascal 7.0 still compiles in under a second on a 486. On DOSBox-X running on modern hardware, it’s instantaneous. The IDE — blue background, yellow text, pull-down menus — is the direct ancestor of the Turbo Vision library that inspired this site’s theme.

I wrote a small unit that reads the RTC via INT 1Ah and formats it as ISO 8601. The entire program, compiled, is 3,248 bytes. Try getting that from a modern toolchain.

What surprised me was not just speed, but focus. Turbo Pascal’s workflow is so tight that experimentation becomes natural: edit, compile, run, inspect, repeat. No dependency resolver, no plugin lifecycle, no hidden build graph. You can reason about the whole stack while staying in flow.

Why it is still worth touching

Turbo Pascal remains one of the best environments for learning low-level software discipline without drowning in tooling:

strong typing with low ceremony
explicit artifacts (.PAS, .TPU, .OBJ, .EXE)
immediate compile-run feedback
clear memory and ABI consequences

If you want to sharpen systems instincts, this is still high-return practice.

Practical 2025 setup that stays reproducible

My baseline:

pin one DOSBox-X config per project
mount a host directory as project root
keep BUILD.BAT for CLI parity with IDE actions
version notes + build profile options in plain text

Expected outcome:

same source builds the same way after a long break
less dependence on undocumented IDE state

What to practice first (30-90 minute labs)

Build a two-unit app and observe incremental rebuild behavior.
Link one external .OBJ routine and verify ABI correctness.
Enable one overlayed cold path and measure first-hit latency.
Initialize BGI with diagnostic harness and test broken path behavior.

These labs map directly to the deeper series below.

Read this as a progression

Related reading:

Batch File Wizardry

Fri, 05 Sep 2025 00:00:00 +0000

DOS batch files have no arrays, no functions, and barely have variables. Yet people built menu systems, BBS doors, and even games with them.

The trick is GOTO and CHOICE (or ERRORLEVEL parsing on older DOS). Combined with FOR loops and environment variable manipulation, you can create surprisingly interactive scripts. We build a file manager menu in pure .BAT that would feel at home on a 1992 shareware disk.

The charm of batch scripting is that constraints are obvious. You cannot hide behind abstractions, so control flow has to be explicit and disciplined. A good .BAT file reads like a state machine: menu, branch, execute, return.

Patterns that still hold up

Use descending IF ERRORLEVEL checks after CHOICE.
Isolate repeated screen/header logic into callable labels.
Validate file paths before launching external tools.
Keep environment variable scope small and predictable.
Always provide a safe “return to menu” path.

These rules prevent the classic batch failure mode: jumping into a dead label or leaving the user in an unexpected directory after an error.

A practical structure is a top menu plus focused submenus (UTIL, DEV, GAMES, NET). Each action should print what it is about to run, execute, and then pause on failure. That tiny bit of observability saves debugging time when scripts grow beyond toy examples.

Batch is primitive, but that is exactly why it teaches sequencing, error handling, and operator empathy so well.

Related reading: