https://github.com/ikelaiah/free-pascal-cookbook
Free Pascal Cookbook
https://github.com/ikelaiah/free-pascal-cookbook
basics cookbook free-pascal freepascal getting-started guide lazarus-ide recipes snippets
Last synced: 2 months ago
JSON representation
Free Pascal Cookbook
- Host: GitHub
- URL: https://github.com/ikelaiah/free-pascal-cookbook
- Owner: ikelaiah
- License: mit
- Created: 2024-08-13T10:29:34.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-12-04T09:04:27.000Z (5 months ago)
- Last Synced: 2025-12-05T21:37:45.041Z (5 months ago)
- Topics: basics, cookbook, free-pascal, freepascal, getting-started, guide, lazarus-ide, recipes, snippets
- Homepage: https://ikelaiah.github.io/free-pascal-cookbook/
- Size: 17.1 MB
- Stars: 11
- Watchers: 1
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
Free Pascal Cookbook | Source Files
This repo contains the source files of my Free Pascal Cookbook, a mkdocs-material-based site.
Explore the docs »
Visit Site
·
View Snippets Repo
## About The Project
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](https://www.freepascal.org) and [Lazarus IDE](https://www.lazarus-ide.org).
## What's Inside
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
## Who Is This For
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
## Getting Started
### Online (Recommended)
The easiest way to start is to visit the cookbook site: [https://ikelaiah.github.io/free-pascal-cookbook](https://ikelaiah.github.io/free-pascal-cookbook)
The site is nicely formatted and easy to navigate. Just pick a topic and start learning!
### Browse Locally
You can also browse the `.md` files directly in this repository. All the content is here; the website just makes it prettier to read.
### Installation
No installation required! Everything you need is already here or linked from the cookbook. To **use** Free Pascal though, you'll need to:
1. Install the [Free Pascal Compiler](https://www.freepascal.org/download.html)
2. (Optional) Install the [Lazarus IDE](https://www.lazarus-ide.org/download/) for a more comfortable development experience
Both are free and work on Windows, macOS, and Linux.
## Compiling Code Snippets
All code snippets in the cookbook are automatically extracted and compiled to ensure they work correctly. You can also experiment with the compiled executables.
### How It Works
The `compile-all-snippets.ps1` PowerShell script:
1. **Scans** all markdown files in the `docs/` directory
2. **Extracts** Pascal code blocks marked with `` ```pascal ``
3. **Classifies** snippets as:
- **Programs**: Complete, runnable programs (contain `program` + `begin`/`end`)
- **Units**: Reusable unit declarations (contain `unit` keyword)
- **Fragments**: Code examples or partial code (learning snippets)
4. **Auto-generates filenames** using the pattern: `{markdown_filename}_{snippet_number}.pas`
- Example: `basic-hello-world_001.pas`, `basic-hello-world_002.pas`
5. **Compiles** all Programs using the Free Pascal compiler (fpc)
6. **Generates executables** you can run and experiment with
7. **Generates reports** summarizing compilation results:
- `snippet_results.csv` - Detailed per-snippet data (machine-readable)
- `REPORT.txt` - Human-readable summary with statistics
### Running Compilation
To compile all snippets:
```powershell
# Basic usage (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"
```
### Build Directory Structure
After running the script, the `build/` folder will contain:
- **Extracted snippets**: `{filename}_{###}.pas` - Source files and units extracted from documentation
- **Compiled executables**: `{filename}_{###}.exe` - 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.
### Support Libraries
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 units
- `synapse` - 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.
### Understanding Results
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.
### Cleaning Up
To remove all compiled artifacts and start fresh:
```cmd
clean-build.bat
```
This removes all `.pas`, `.exe`, `.ppu`, `.o`, `.log` files and the reports.
### Skipping Compilation for Specific Snippets
Some code examples may intentionally contain memory leaks, unsafe patterns, or other issues suitable for educational discussion but not for automated compilation. Use the `` marker to prevent a snippet from being compiled:
```
'''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 a note in the extracted file explaining why it was skipped
## Featured Topics
New to Free Pascal? Start with these:
- [**Hello, World!**](docs/basics/basic-hello-world.md) - Your first Free Pascal program (choose IDE or CLI)
- [**Data Types**](docs/basics/common-data-types.md) - Understanding numbers, text, and other data
- [**Control Flow**](docs/basics/) - Making decisions with `if` and looping with `for`/`while`
- [**Functions & Procedures**](docs/basics/) - Writing code you can reuse
- [**Introduction to Object Pascal**](docs/basics/intro-objpas-fpc.md) - Explore classes and OOP concepts
## Getting Help
**Have a question?** Here are some places to find help:
- **Stuck on something in this cookbook?** Open an [issue on GitHub](https://github.com/ikelaiah/free-pascal-cookbook/issues) and I'll help!
- **Want to learn more?** Check out the [Free Pascal Wiki](https://wiki.freepascal.org/) and [Lazarus documentation](https://wiki.lazarus.freepascal.org/)
- **Join the community:**
- [Unofficial Free Pascal Discord](https://discord.gg/3VdxbSFyJP)
- [Free Pascal & Lazarus Forum](https://forum.lazarus.freepascal.org/)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/freepascal) - Tag your questions with `freepascal`
## Contributing
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](https://github.com/ikelaiah/free-pascal-cookbook/issues)
- **Suggest improvements** - Have ideas for new topics or better explanations? [Start a discussion](https://github.com/ikelaiah/free-pascal-cookbook/issues)
- **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.
## License
Distributed under the MIT License. See `LICENSE.md` for more information.
## Contact
Iwan Kelaiah - https://au.linkedin.com/in/ikelaiah
Project Link: [https://github.com/ikelaiah/free-pascal-cookbook](https://github.com/ikelaiah/free-pascal-cookbook)
## Acknowledgments
- 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;
- [Unofficial Free Pascal discord server](https://discord.com/channels/570025060312547359/570091337173696513).
- [Free Pascal & Lazarus forum](https://forum.lazarus.freepascal.org/index.php).
- [Tweaking4All Delphi, Lazarus, Free Pascal forum](https://www.tweaking4all.com/forum/delphi-lazarus-free-pascal/).
- [Laz Planet - Blogspot](https://lazplanet.blogspot.com) / [Laz Planet - GitLab](https://lazplanet.gitlab.io).
- [Delphi Basics](https://www.delphibasics.co.uk/index.html).