Appendix B: Free Pascal and Lazarus Installation Guide

This appendix walks you through installing Free Pascal Compiler (FPC) and the Lazarus IDE on Windows, macOS, and Linux. By the end, you will have a working Pascal development environment with a verified test compile. If you encounter problems, the troubleshooting section at the end covers the most common issues.

B.1 Overview: What You Are Installing

There are two main components:

Free Pascal Compiler (FPC): The command-line compiler that translates Pascal source code into native executables. FPC supports dozens of platforms and CPU architectures. The current stable release is FPC 3.2.2 (check freepascal.org for the latest).
Lazarus IDE: A full-featured integrated development environment built on top of FPC. Lazarus provides a visual form designer, code editor with syntax highlighting and code completion, integrated debugger, and a component library (LCL) for building GUI applications. Lazarus is optional for console programs, but strongly recommended for this textbook.

You can use FPC alone from the command line for all non-GUI chapters. You need Lazarus for the GUI chapters (Part V and beyond).

B.2 Windows Installation

Step 1: Download the Installers

Visit the following URLs and download the installers appropriate for your system (almost always 64-bit / x86_64):

FPC: https://www.freepascal.org/download.html — choose the Windows installer (.exe)
Lazarus: https://www.lazarus-ide.org/index.php?page=downloads — choose the Windows 64-bit installer (.exe)

Alternatively, download the combined Lazarus installer, which bundles FPC and Lazarus together. This is the easiest option for most users.

Step 2: Install FPC (If Installing Separately)

Run the FPC installer (fpc-3.2.2.i386-win32.exe or the 64-bit variant).
Accept the license agreement.
Choose the installation directory. The default (C:\FPC\3.2.2\) is fine. Avoid paths with spaces.
Select components. Keep all defaults checked.
The installer will offer to add FPC to your system PATH. Accept this option.
Complete the installation.

Step 3: Install Lazarus

Run the Lazarus installer (lazarus-3.x-fpc-3.2.2-win64.exe).
Accept the license agreement.
Choose the installation directory. The default (C:\Lazarus\) is recommended. Avoid paths with spaces.
If you installed FPC separately, point the installer to your FPC directory when prompted.
Select components. Keep all defaults checked, including "Associate .pas and .lpr files."
Complete the installation.

Step 4: Verify PATH Configuration

Open a new Command Prompt or PowerShell window and type:

fpc -v

You should see output like:

Free Pascal Compiler version 3.2.2 [2021/05/15] for x86_64

If you get "command not found," you need to add FPC to your PATH manually:

Open Settings > System > About > Advanced system settings > Environment Variables.
Under "System variables," find Path and click Edit.
Add the FPC bin directory (e.g., C:\FPC\3.2.2\bin\x86_64-win64\).
Click OK, close all dialogs, and open a new terminal to test.

Step 5: Test Compile

Create a file called test.pas with the following contents:

program Test;
begin
  WriteLn('Free Pascal is working!');
end.

Compile and run:

fpc test.pas
test.exe

You should see Free Pascal is working! printed.

B.3 macOS Installation

Option A: Using Homebrew (Recommended)

If you have Homebrew installed (https://brew.sh), this is the simplest approach:

brew install fpc
brew install --cask lazarus

Homebrew handles dependencies and PATH configuration automatically.

Option B: Using the Official Installers

Install Xcode Command Line Tools (required for the linker):

xcode-select --install

Follow the dialog that appears. This installs the system C toolchain, which FPC uses for linking.

Download FPC: Visit https://www.freepascal.org/download.html and download the macOS installer package (.dmg or .pkg). Run the installer and follow the prompts.
Download Lazarus: Visit https://www.lazarus-ide.org/index.php?page=downloads and download the macOS package. You will typically find three DMGs: - fpc-3.2.2.intel-macosx.dmg (FPC for Intel Macs) - fpc-3.2.2.aarch64-macosx.dmg (FPC for Apple Silicon) - lazarus-3.x-macosx-x86_64.dmg (Lazarus IDE) - fpcsrc-3.2.2.dmg (FPC source — optional, useful for debugging)

Install FPC first, then Lazarus.

Apple Silicon (M1/M2/M3) Notes: - As of FPC 3.2.2, the native AArch64 compiler is fully supported. - If you use the Intel version, it runs under Rosetta 2 without issues. - Lazarus works natively on Apple Silicon with the latest stable release.

Verify Installation

Open Terminal and type:

fpc -v

If it reports the version, FPC is correctly installed. Then open Lazarus from the Applications folder.

macOS Gatekeeper Warning

The first time you open Lazarus, macOS may block it because it is not signed through the App Store. To allow it:

Go to System Settings > Privacy & Security.
Scroll down to the security section.
Click Open Anyway next to the Lazarus warning.

You may need to do this once for each Lazarus component (the IDE, the debugger, and the compiler).

B.4 Linux Installation

Debian / Ubuntu / Linux Mint

sudo apt update
sudo apt install fpc lazarus

This installs both FPC and Lazarus from the distribution repository. The packaged version may lag behind the latest release by one or two versions, but it will work well for this textbook.

For the latest version, use the SourceForge packages:

# Download .deb files from sourceforge.net/projects/lazarus/files/
# Install in order:
sudo dpkg -i fpc-laz_3.2.2-1_amd64.deb
sudo dpkg -i fpc-src_3.2.2-1_amd64.deb
sudo dpkg -i lazarus-project_3.6-0_amd64.deb
sudo apt install -f    # Fix any missing dependencies

Fedora / RHEL / CentOS

sudo dnf install fpc lazarus

Arch Linux / Manjaro

sudo pacman -S fpc lazarus

The Arch repository typically has very recent versions.

openSUSE

sudo zypper install fpc lazarus

Building from Source (Any Distribution)

If your distribution does not package FPC/Lazarus, or you need the absolute latest version:

Bootstrap FPC: You need an existing FPC to compile FPC. Download a binary bootstrap from freepascal.org:

# Download and extract the FPC binary release
tar xzf fpc-3.2.2.x86_64-linux.tar
cd fpc-3.2.2.x86_64-linux
sudo ./install.sh

Build FPC from source (optional):

git clone https://gitlab.com/freepascal.org/fpc/source.git fpc-source
cd fpc-source
make clean all
sudo make install PREFIX=/usr/local

Build Lazarus from source:

# Install GTK2 development libraries first
sudo apt install libgtk2.0-dev   # Debian/Ubuntu
# or
sudo dnf install gtk2-devel      # Fedora

git clone https://gitlab.com/freepascal.org/lazarus/lazarus.git
cd lazarus
make clean all
sudo make install PREFIX=/usr/local

Verify Installation

fpc -v
lazarus-ide &

B.5 IDE Configuration

Once Lazarus is installed, launch it and configure the following settings.

Compiler Path

Go to Tools > Options > Environment > Compiler and verify the path to the FPC executable:

Windows: C:\FPC\3.2.2\bin\x86_64-win64\fpc.exe
macOS: /usr/local/bin/fpc or /opt/homebrew/bin/fpc
Linux: /usr/bin/fpc or /usr/local/bin/fpc

FPC Source Directory

Go to Tools > Options > Environment > FPC Source and set the path to the FPC source code directory. This enables code navigation into the standard library:

Windows: C:\FPC\3.2.2\source\ or C:\lazarus\fpc\3.2.2\source\
macOS/Linux: /usr/share/fpcsrc/ or wherever you installed the source

Editor Settings

Go to Tools > Options > Editor:

General: Tab width 2, use spaces instead of tabs (recommended for consistent formatting).
Display: Enable line numbers, bracket matching, and code folding.
Completion: Enable identifier completion (Ctrl+Space) and auto-close brackets.
Color: Choose a color scheme you find comfortable. "Pascal Classic" and "Delphi" are popular choices.

Creating a Console Project

Go to Project > New Project.
Select Simple Program (not "Application" — that creates a GUI project).
Lazarus generates a minimal program skeleton.
Save the project (Ctrl+Shift+S) to a directory of your choice.
Press F9 to compile and run.

Creating a GUI (LCL) Project

Go to Project > New Project.
Select Application.
Lazarus creates a form (Form1) and the project file (.lpr).
Use the visual designer to place components on the form.
Press F9 to compile and run.

Project Templates for This Textbook

For chapters that focus on console programs (Parts I-IV), use Simple Program. For GUI chapters (Part V onward), use Application. Save each chapter's work in its own project directory to keep things organized.

B.6 Alternative Editors and Workflows

While Lazarus is the recommended IDE, you can use FPC from the command line with any text editor:

VS Code with OmniPascal or Pascal Extension

Install Visual Studio Code.
Install the "OmniPascal" or "Pascal" extension from the marketplace.
Configure the extension to point to your FPC installation.
Compile from the integrated terminal: fpc myprogram.pas

Vim / Neovim

Use the vim-pascal syntax plugin or configure Tree-sitter for Pascal highlighting. Compile with :!fpc %.

Emacs

The pascal-mode is built into Emacs. For richer support, look for opascal-mode (Object Pascal).

Command-Line Compilation

# Basic compilation
fpc program.pas

# With debug info
fpc -g program.pas

# With optimizations
fpc -O2 program.pas

# Specify output directory
fpc -FE./bin program.pas

# Delphi mode
fpc -Mdelphi program.pas

# ObjFPC mode (default)
fpc -Mobjfpc program.pas

# Show all warnings and hints
fpc -vwh program.pas

B.7 Troubleshooting Common Issues

"fpc: command not found"

The FPC binary is not on your system PATH. Add the FPC bin directory to your PATH environment variable (see platform-specific instructions above).

"Can't find unit SysUtils" or Other Standard Units

FPC cannot find its unit library. Check that the FPC library path is correct:

fpc -vt test.pas

This verbose output shows where FPC searches for units. Verify those paths contain .ppu files.

Lazarus Reports "FPC source directory not found"

Open Tools > Options > Environment > FPC Source and browse to the correct directory. If you did not install the FPC source package, install it:

Debian/Ubuntu: sudo apt install fpc-source
Fedora: sudo dnf install fpc-src
Windows/macOS: Reinstall from the .dmg/.exe and ensure "FPC Source" is checked.

Linking Errors on macOS ("ld: library not found for -lSystem")

You are missing the Xcode Command Line Tools. Install them:

xcode-select --install

If already installed, check that the SDK path is correct:

xcrun --show-sdk-path

"Error: Illegal parameter: -dUseCThreads" on Linux

Some older project files reference the cthreads unit incorrectly. Add cthreads to the uses clause of your .lpr file manually:

uses
  {$IFDEF UNIX}cthreads,{$ENDIF}
  Classes, SysUtils;

GTK/Widget Set Errors on Linux

If Lazarus fails to compile or run with widget set errors, ensure you have the GTK development headers:

# For GTK2 (default on most systems)
sudo apt install libgtk2.0-dev

# For Qt5
sudo apt install libqt5pas-dev

To switch widget sets in Lazarus: Tools > Options > Environment > LCL Widget Type.

32-bit vs. 64-bit Mismatch

If you get errors about incompatible object files or "skipping incompatible library," your FPC and Lazarus are built for different architectures. Ensure both are the same (either both 32-bit or both 64-bit). On modern systems, 64-bit is strongly recommended.

Cross-Compilation Not Working

Cross-compilation requires installing the FPC cross-compiler packages for the target platform. This is an advanced topic; for most readers of this textbook, compiling natively for your own platform is sufficient.

Antivirus Blocking Compilation (Windows)

Some antivirus programs flag newly compiled executables as suspicious. Add your project directory and the FPC installation directory to your antivirus exclusion list.

Lazarus Crashes on Startup

Delete the Lazarus configuration directory and restart:

Windows: %LOCALAPPDATA%\lazarus\
macOS: ~/.lazarus/
Linux: ~/.lazarus/

Lazarus will recreate its configuration from defaults.

B.8 Keeping Your Installation Updated

Checking Your Version

fpc -v                     # Shows FPC version
lazbuild --version         # Shows Lazarus build tool version

Updating

Homebrew (macOS): brew update && brew upgrade fpc lazarus
Debian/Ubuntu: sudo apt update && sudo apt upgrade fpc lazarus
Arch: sudo pacman -Syu fpc lazarus
Windows/manual installs: Download the new installer from the official website and install over the existing installation, or uninstall first and then reinstall.

Compatibility Note

This textbook targets FPC 3.2.x and Lazarus 3.x. All code examples have been tested against these versions. If you use an older version (FPC 3.0.x), most code will still work, but generics syntax and some newer features may differ. If you use a newer version (FPC 3.4+, when released), everything should remain compatible.

You are now ready to write, compile, and run Pascal programs. Return to Chapter 1 to begin.