Introducing PasBuild 1.0.0 - Maven-Inspired Build Tool for Free Pascal

[Graeme]

Hi all,

I'm excited to announce the first release of PasBuild v1.0.0, a
modern build automation tool for Free Pascal projects inspired by
Apache Maven!

GitHub: https://github.com/graemeg/PasBuild


Why PasBuild?
=============

While fpmake is powerful, it can be laborious to create and
maintain, especially for large projects. A real-world example:
fpGUI Toolkit has 120+ units, include files in various locations,
and platform-dependent directory trees. The fpmake.pp file was
40KB with over 750 lines of code that needed constant updates when
adding or removing units.

PasBuild's project.xml? Just 3KB and 117 lines - and we know how
verbose XML is. ;-) No updates needed when units change - it
self-discovers your code and dynamically builds the FPC command!


Key Features
============

Convention Over Configuration
-----------------------------
- Standard directory layout (src/main/pascal, src/test/pascal)
- Zero configuration for projects following conventions
- Override only what you need to customize

Intelligent Automation
----------------------
- Auto-discovers all units and subdirectories
- Automatic include path detection (*.inc files)
- Self-maintaining - add/remove files without updating config
- Cross-platform path handling (src/main/pascal → src\main\pascal)

Complete Build Lifecycle
-------------------------
- clean: Remove build artifacts
- compile: Build your executable or library
- test: Compile and run tests (FPCUnit/FPTest auto-detection)
- package: Create release archives
- source-package: Generate source distributions

Build Profiles
--------------
- Define multiple build configurations (debug, release, etc.)
- Activate single or multiple profiles: -p base,debug,logging
- Profile-specific compiler options and defines
- Perfect for cross-platform conditional compilation

Resource Management
-------------------
- Automatic resource copying to target directory
- Variable filtering: ${project.version} → 1.0.0
- Supports both main and test resources
- Version injection via resource filtering

Developer-Friendly
------------------
- Single XML configuration file (project.xml)
- Semantic versioning 2.0.0 with pre-release tags
- Verbose mode for debugging (-v flag)
- Alternate project files support (-f custom.xml)
- Maven-style goal dependencies

Cross-Platform
--------------
- Works identically on Linux, Windows, macOS, FreeBSD
- Automatic path separator handling
- Platform-specific conditional compilation support

Self-Hosting
------------
- PasBuild builds itself using project.xml
- Demonstrates best practices
- Easy to bootstrap from source


Real-World Testing
==================

PasBuild has been extensively tested with:
- Multiple production applications
- fpGUI Toolkit (120+ units, complex structure)
- Projects with platform-dependent code trees
- Libraries and applications alike


Example: Minimal project.xml
=============================

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

  <build>
    <mainSource>Main.pas</mainSource>
    <executableName>myapp</executableName>
  </build>
</project>

That's it! PasBuild handles the rest automatically.


Getting Started
===============

# Bootstrap compilation
mkdir -p target/units
echo '1.0.0' > target/version.inc
fpc -Mobjfpc -O1 -FEtarget -FUtarget/units -Fitarget \
    -Fusrc/main/pascal src/main/pascal/PasBuild.pas

# Now use PasBuild to build itself
./target/pasbuild compile

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


Documentation
=============

Comprehensive documentation available in the repository:
- Quick Start Guide: docs/quick-start-guide.adoc
- Design Document: docs/design.adoc
- Bootstrap Instructions: BOOTSTRAP.txt


Try It Today!
=============

Clone from GitHub:
  git clone https://github.com/graemeg/PasBuild.git

Your feedback and contributions are welcome! Please
kindly use the GitHub Issue Tracker.

More features to come soon.

License: BSD-3-Clause


Regards,
  - Graeme -


--
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

[Thaddy]

Promising, will definitely test it.

[Roland57]

Very interesting. Thank you for sharing.

Tested successfully under Linux. Now I will take time to try it with a real project.

[plaza1518]

Hello Graeme!

Really great work! I read through the information on your GitHub repository and, if I may offer my humble opinion, was pleasantly surprised by how professional your work is. I therefore have high hopes that your build tool will also become standard.

As far as I understand your build tool, it has “fpc” as its sole source and target. Are there plans for it to “work together” with the build configuration for lazbuild (lpi, lpk)? Do you have any thoughts about allowing Lazarus users to use your build tool so that it works, for example, with regard to the automatic analysis/integration of unit and include paths? Or the various profiles that can also be conveniently combined with your build tool?

I would understand very well if your build tool differs from Lazarus (on the other hand, I would be happy about “compatibility”). Do you think it would make sense to make a note about this in the readme?

[BSaidus]

Wow, great job.
Do you think that PasBuild can be an alternative and replace MSBuild ?

[Graeme]

Hi. Thank you for the kind words.  I think the corporate world is rubbing off on my open source projects - where everything needs to be thoroughly discovered before implementation starts. :-)

As far as I understand your build tool, it has “fpc” as its sole source and target. Are there plans for it to “work together” with the build configuration for lazbuild (lpi, lpk)? Do you have any thoughts about allowing Lazarus users to use your build tool so that it works

I'm specifically targeting Free Pascal-based projects.

As I mentioned in the documentation, after returning to Object Pascal from working with Java for a few years, I quickly realized what a mess the Object Pascal build ecosystem is. By that, I mean the build heterogeneity. For instance, if I create a new project and need to use three or four frameworks (e.g., Indy, tiOFP) to build my application, each one often has different build instructions.

In the Java world, nearly every project can be built simply by running 'mvn verify' or 'gradlew build'. No further instructions are typically needed.

Why can't the Object Pascal ecosystem be similar? This is why I created PasBuild. Fingers crossed it eventually catches on, as others can clearly see how convenient it is to easily build any third-party framework or tool.

I'm currently updating all my open-source projects to use PasBuild, so more and more usage examples should appear soon.

I fully understand Lazarus is extremely popular (I've used it for well over a decade in commercial work), but I also use other IDEs and editors. I also constantly commit using Git. Therefore, I already operate heavily in the command line. Being able to build, test, and package my projects from the command line simply makes sense for my workflow. Crucially, anyone can still use their IDE or editor of choice—PasBuild doesn't affect or replace that at all. That is not its purpose.

As for lazbuild, I've never really used it. I'm not sure how useful a lazbuild-to-pasbuild converter would be, because that still wouldn't enforce or improve the source code and resources organization (the convention I'm proposing with PasBuild).

It's definitely something I'll keep in mind, but I still have higher-priority features to implement in PasBuild first, such as:

* Multi-module projects (projects inside a project).
* Automatic dependency management (which I really want to look into).

[Graeme]

Do you think that PasBuild can be an alternative and replace MSBuild ?

I haven't used MSBuild, but quickly doing an internet search, I can't see why PasBuild can't compete in the same arena. Also, MSBuild seems tightly tied to .NET Core, so I'm assuming it has .NET dependencies. I'm yet to see a Linux distro, or FreeBSD or MacOS that ships with .NET libraries as standard. So that's just another hurdle standing in the way of building a project quickly.

PasBuild targets Free Pascal-based projects. PasBuild only needs FPC installed to bootstrap the first binary. After that, PasBuild can build itself.

[Graeme]

Tested successfully under Linux.

Fantastic - I guess that means my bootstrap instructions were clear enough. That's a relief. 

[dbannon]

Graham, with a superficial look, looks great. I currently use some quite horrible bash scripts. A question -

I like the idea of "sensible" names for directories. I use sensible but different names ! Is it possible to have a config file that recognizes a different subset of "sensible" ?

Davo

 

[Graeme]

I like the idea of "sensible" names for directories. I use sensible but different names ! Is it possible to have a config file that recognizes a different subset of "sensible" ?

Yes, source and target locations can be user-configured. PasBuild doesn't force the convention it proposes. Most things can be configured, but that makes for a larger `project.xml` file. If you stick to the convention, then nearly nothing needs to be configured. It will try and auto-discover as much as possible.

[PascalDragon]

As I mentioned in the documentation, after returning to Object Pascal from working with Java for a few years, I quickly realized what a mess the Object Pascal build ecosystem is. By that, I mean the build heterogeneity. For instance, if I create a new project and need to use three or four frameworks (e.g., Indy, tiOFP) to build my application, each one often has different build instructions.

In the Java world, nearly every project can be built simply by running 'mvn verify' or 'gradlew build'. No further instructions are typically needed.

Why can't the Object Pascal ecosystem be similar? This is why I created PasBuild. Fingers crossed it eventually catches on, as others can clearly see how convenient it is to easily build any third-party framework or tool.

Considering that not everyone will migrate, congrats, XKCD: Standards applies.

[Graeme]