PasBuild

A Maven-inspired build automation tool for Free Pascal projects.

Table of Contents

• 1. What is PasBuild?
• 2. Features
• 3. Convention Over Configuration
• 4. Quick Start
  • 4.1. 30-Second Start
• 5. Documentation
• 6. Requirements
• 7. License
• 8. Contributing
• 9. Acknowledgments

1. What is PasBuild?

PasBuild is a command-line build tool for Free Pascal that brings Maven-like conventions and lifecycle management to Pascal development. It follows the principle of convention over configuration with sensible defaults, allowing you to override only what you need to change.

2. Features

Core Functionality:

• ✅ pasbuild clean - Removes build artifacts

• ✅ pasbuild compile [-p profile] - Compiles with FPC

• ✅ pasbuild test-compile - Compiles tests (compile → test-compile)

• ✅ pasbuild test - Runs tests (compile → test-compile → test)

• ✅ pasbuild package - Creates ZIP archive (clean → compile → package)

• ✅ pasbuild init - Bootstraps new projects

• ✅ --help / --version - Built-in help system

Advanced Features:

• ✅ Build profiles (debug/release with custom compiler options)

• ✅ Multiple test frameworks (FPCUnit, FPTest) with auto-detection

• ✅ Automatic dependency resolution between goals

• ✅ Duplicate goal prevention

• ✅ Fail-fast error handling

• ✅ Cross-platform path handling (Maven convention)

• ✅ Self-hosting (PasBuild can build itself)

• ✅ Zero memory leaks (verified with -gh)

• ✅ Multi-module projects with dependency resolution

• ✅ Topological build ordering with cycle detection

• ✅ Module selection flag (-m) for selective builds

Platform Support:

• ✅ Linux

• ✅ FreeBSD

• ✅ macOS

• ✅ Windows

3. Convention Over Configuration

PasBuild follows Maven’s philosophy: sensible defaults mean minimal configuration.

Default Directory Layout:

myproject/
├── project.xml          # Minimal configuration
├── src/
│   ├── main/
│   │   └── pascal/      # Your source files here
│   │       └── Main.pas
│   └── test/
│       └── pascal/      # Your test files here
│           └── TestRunner.pas
└── target/              # Build output (auto-created)
    ├── myproject        # Compiled executable
    ├── TestRunner       # Compiled test runner
    ├── units/           # Compiled units (.ppu, .o)
    ├── test-units/      # Compiled test units
    └── myproject-1.0.0.zip  # Package archive

Minimal Configuration:

Just define your project metadata - everything else uses sensible defaults:

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <name>MyProject</name>
  <version>1.0.0</version>
  <author>Your Name</author>
  <license>BSD-3-Clause</license>

  <build>
    <mainSource>Main.pas</mainSource>
    <executableName>myproject</executableName>
  </build>

  <test>
    <framework>auto</framework>           <!-- auto-detect FPCUnit or FPTest -->
    <testSource>TestRunner.pas</testSource>
    <frameworkOptions>
      <option>--all</option>              <!-- Run all tests -->
    </frameworkOptions>
  </test>
</project>

What You Get for Free:

• Automatic unit path scanning (-Fu flags)

• Automatic include path scanning (-Fi flags for .inc files)

• Test framework auto-detection (FPCUnit/FPTest)

• Separate test compilation (Maven-style target/test-units)

• Cross-platform executable naming (.exe on Windows)

• Standard output directories (target/)

• Archive creation with LICENSE and README inclusion

• Profile-based builds without code changes

Only Override What You Need:

<profiles>
  <profile>
    <id>release</id>
    <defines>
      <define>RELEASE</define>
    </defines>
    <compilerOptions>
      <option>-O3</option>      <!-- Override optimization -->
      <option>-CX</option>      <!-- Smart linking -->
      <option>-XX</option>      <!-- Strip symbols -->
    </compilerOptions>
  </profile>
</profiles>

4. Quick Start

See Quick Start Guide for detailed usage instructions.

4.1. 30-Second Start

# Install PasBuild (bootstrap from source)
git clone https://github.com/graemeg/pasbuild.git
cd pasbuild
./bootstrap.sh  # See BOOTSTRAP.txt for manual steps

# Create a new project
mkdir myapp && cd myapp
pasbuild init

# Build and run
pasbuild compile
./target/myapp

# Run tests
pasbuild test

# Create release package
pasbuild package

5. Documentation

• Quick Start Guide - Getting started with PasBuild

• Design Document - Architecture and design rationale

• Implementation Progress - Development roadmap

• Bootstrap Instructions - First-time compilation

6. Requirements

• Free Pascal Compiler (FPC) 3.2.2 or later

• FPC must be in your system PATH

7. License

Copyright (c) 2025 Graeme Geldenhuys

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

All source files in this project are covered by this license unless otherwise noted.

8. Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

9. Acknowledgments

• Inspired by Apache Maven’s convention-over-configuration philosophy

• Built with Free Pascal Compiler

• Uses FPC’s standard library units (zipper, DOM, XMLRead)