This repo contains the source files of my Free Pascal Cookbook, a mkdocs-material-based site.
Explore the docs »
Visit Site
·
View Snippets Repo
Learn Free Pascal with practical, ready-to-run examples. Whether you're a complete beginner or exploring Object-Oriented Pascal, this cookbook covers everything from "Hello, World!" to advanced concepts like generics and interfaces.
This cookbook is a collection of tutorials, code examples, and study notes for the Free Pascal programming language and Lazarus IDE.
This cookbook covers:
- Basics - Variables, data types, and getting started with Free Pascal
- Control Flow - Loops, conditions, and making decisions in code
- Functions & Procedures - Writing reusable code and organizing your programs
- Object-Oriented Programming - Classes, inheritance, encapsulation, and interfaces
- Advanced Topics - Generics, pointers, and working with memory
- Practical Examples - Real, ready-to-run code you can test immediately
This cookbook is designed for:
- Complete beginners to programming who want to learn Free Pascal from scratch
- High school students (ages 15-18) exploring programming languages
- Developers familiar with other languages who want to explore Object Pascal
- Hobbyists interested in learning Free Pascal and Lazarus IDE
- Anyone looking for clear, practical examples and explanations
The easiest way to start is to visit the cookbook site: https://ikelaiah.github.io/free-pascal-cookbook
The site is nicely formatted and easy to navigate. Just pick a topic and start learning!
You can also browse the .md files directly in this repository. All the content is here; the website just makes it prettier to read.
No installation required! Everything you need is already here or linked from the cookbook. To use Free Pascal though, you'll need to:
- Install the Free Pascal Compiler
- (Optional) Install the Lazarus IDE for a more comfortable development experience
Both are free and work on Windows, macOS, and Linux.
The production/tested setup for this cookbook is FPC 3.2.2 with Lazarus IDE 4.0. Snippet validation runs on Windows and Linux.
All code snippets in the cookbook are automatically extracted and compiled to ensure they work correctly. You can also experiment with the compiled executables.
The compile-all-snippets.ps1 PowerShell script:
- Scans all markdown files in the
docs/directory - Extracts Pascal code blocks marked with
```pascal - Classifies snippets as:
- Programs: Complete, runnable programs (contain
program+begin/end) - Units: Reusable unit declarations (contain
unitkeyword) - Fragments: Code examples or partial code (learning snippets)
- Programs: Complete, runnable programs (contain
- Auto-generates filenames using the pattern:
{markdown_filename}_{snippet_number}.pas- Example:
basic-hello-world_001.pas,basic-hello-world_002.pas
- Example:
- Compiles all Programs using the Free Pascal compiler (fpc)
- Generates executables you can run and experiment with
- Generates reports summarizing compilation results:
snippet_results.csv- Detailed per-snippet data (machine-readable)REPORT.txt- Human-readable summary with statistics
To compile all snippets:
# Windows PowerShell (uses default paths: .\docs input, .\build output)
.\compile-all-snippets.ps1
# Custom paths
.\compile-all-snippets.ps1 -DocsPath ".\docs" -OutputDir ".\build" -FpcBin "C:\fpc\bin\fpc.exe"
# Linux with PowerShell 7; FPC and Lazarus are discovered from standard locations
pwsh ./compile-all-snippets.ps1After running the script, the build/ folder will contain:
- Extracted snippets:
{filename}_{###}.pas- Source files and units extracted from documentation - Compiled executables:
{filename}_{###}.exeon Windows or{filename}_{###}on Unix - Runnable programs (for Programs only) - Compiled units:
*.ppu, *.o- Object files and compiled units - Logs:
{filename}_{###}.log- Compiler output and error messages - Reports:
snippet_results.csv,REPORT.txt- Compilation statistics
All extracted units and programs are stored directly in build/ for easy discovery and experimentation.
The build_support/ folder contains third-party and supplementary units required for compilation:
-
build_support/units/- Third-party unit source files:ezthreads- Threading and concurrency unitssynapse- Network and HTTP communication units- Other specialized libraries for cookbook examples
-
build_support/libs/- External compiled libraries:sqlite3.dll- SQLite database library- Other platform-specific libraries
These support files allow the snippets to compile with all necessary dependencies. Simply run compile-all-snippets.ps1 and it will automatically locate and compile against these units and libraries.
Bundled third-party support files retain their original licenses. See THIRD_PARTY_NOTICES.md for attribution and license notes.
The script reports:
- SUCCESS: Program compiled without errors ✅
- FAILED: Program has compilation errors (check .log files for details) ❌
- SAVED: Unit or fragment extracted and saved for reference (not compiled) 💾
- SKIPPED: Fragment or partial code (cannot be compiled standalone)
Check build/REPORT.txt or build/snippet_results.csv for detailed results.
If any compilable program fails, the script exits with a non-zero status so CI can catch the regression.
To remove all compiled artifacts and start fresh:
clean-build.batThis removes all .pas, .exe, .ppu, .o, .log files and the reports.
Some code examples may intentionally contain memory leaks, unsafe patterns, require a newer FPC version, or demonstrate another case that should not be compiled by the FPC 3.2.2 validation run. Use the <!-- SKIP_COMPILE --> marker, optionally with a reason, to prevent a snippet from being compiled:
<!-- SKIP_COMPILE: intentional memory leak demo -->
```pascal
program MemoryLeakExample;
{ This demonstrates a memory leak for educational purposes }
begin
// intentional memory leak shown here
end.
```The script will:
- Still extract and save the snippet for reference
- Mark it as non-compilable to avoid failures
- Include the skip reason in the extracted file and
snippet_results.csv
New to Free Pascal? Start with these:
- Hello, World! - Your first Free Pascal program (choose IDE or CLI)
- Data Types - Understanding numbers, text, and other data
- Control Flow - Making decisions with
ifand looping withfor/while - Functions & Procedures - Writing code you can reuse
- Introduction to Object Pascal - Explore classes and OOP concepts
Have a question? Here are some places to find help:
- Stuck on something in this cookbook? Open an issue on GitHub and I'll help!
- Want to learn more? Check out the Free Pascal Wiki and Lazarus documentation
- Join the community:
- Unofficial Free Pascal Discord
- Free Pascal & Lazarus Forum
- Stack Overflow - Tag your questions with
freepascal
This is an open source project! If you find errors, have suggestions, or want to add examples, I'd love your help.
You can:
- Report issues - Found a typo, unclear explanation, or code error? Open an issue
- Suggest improvements - Have ideas for new topics or better explanations? Start a discussion
- Submit pull requests - Feel free to fork, improve, and submit PRs!
For major changes, please open an issue first to discuss what you'd like to change.
Distributed under the MIT License. See LICENSE.md for more information.
Bundled third-party support units keep their original licenses. See THIRD_PARTY_NOTICES.md for details.
Iwan Kelaiah - https://au.linkedin.com/in/ikelaiah
Project Link: https://github.com/ikelaiah/free-pascal-cookbook
-
The FPC devs for sharing the joy of Object Pascal.
-
The Lazarus IDE devs for making such an amazing IDE.
-
The dedicated people behind various units/modules in OPM.
-
The kind and helpful individuals on various online platforms such as;