= Blaise Pascal Compiler
:icons: font
:source-highlighter: rouge

image:https://github.com/graemeg/blaise/actions/workflows/bootstrap.yml/badge.svg["Build status", link="https://github.com/graemeg/blaise/actions/workflows/bootstrap.yml"]

**The Pascal you love, reimagined for the modern era.**

Blaise is a next-generation Object Pascal compiler built from the ground up to eliminate decades of legacy baggage. It prioritizes developer productivity, memory safety, and high-performance execution.


== ✨ The Vision

The Object Pascal ecosystem has two options: Embarcadero Delphi (proprietary,
Windows-first) and Free Pascal (open source but carrying 30 years of accumulated
complexity — five language modes, five string types, and thousands of include files).

This compiler takes a different approach:

* *One language mode.* No `{$mode}` switches; no legacy dialect support.
* *One string type.* UTF-8 reference-counted string and 0-based indexing. `RawBytes` for binary data.
* *Type names that say what they mean.* `Int` / `UInt` are the machine's
  pointer-sized integers; `Int8` .. `Int64`, `UInt8` .. `UInt64`, `Float32` and
  `Float64` state their width, and `Float` is always `Float64`.  FPC's
  `Integer` was frozen at 32 bits two decades ago; the classic names are
  retired to an opt-in `ClassicPascalTypes` unit (see
  link:docs/type-standardisation-design.adoc[the design]).
* *One memory model.* Automatic reference counting applies uniformly to
  strings, classes, and interfaces. No manual/auto split between `TObject`
  and `TInterfacedObject`; `[Weak]` breaks cycles. `Free` is retained as a
  synonym for immediate release.
* *Clean interfaces.* No COM GUIDs; interface dispatch via compile-time vtable mapping.
* *Reified generics.* Monomorphization at compile time — no type erasure.
* *Modern build system.* PasBuild with `project.xml`; no makefiles.
* *First-class debugger.* OPDF is the default debug format; DWARF is not required.

See link:docs/design.adoc[docs/design.adoc] for the full architecture and
implementation plan.

The result — A modern, cross-platform Object Pascal compiler that generates
native code directly, with its own assembler and linker.
Single language mode, single string type, zero-GUID interfaces, reified
generics, and first-class
https://github.com/graemeg/opdebugger[OPDF] debug format support — including
full source-level debugging of incrementally-compiled multi-unit programs.


== 🚀 Project Status

* **Self-Hosting:** Yes. Blaise bootstraps and recompiles itself with byte-for-byte fixpoint. FPC is no longer required — the entire toolchain runs on Blaise alone.
* **Testing:** 5161+ compiler tests and 389 stdlib tests, and growing (Test-Driven Development from day one). The test suite itself compiles under Blaise, and runs in CI on Linux, FreeBSD and macOS.
* **Backends:** A direct native code generator for x86-64 and arm64.  Blaise started out on https://c9x.me/compile/[QBE], which got it running with the least effort while the native backend was built; as planned, QBE was removed in v0.15.0 once the native backend had caught up (see link:docs/toolchain-independence.adoc[docs/toolchain-independence.adoc]).
* **Targets:** Three targets — macOS arm64 (the primary development host since v0.15.0), Linux x86_64 and FreeBSD x86_64 — with cross-compilation between them using no external tools or packages: the internal assembler and linker produce the foreign binary directly, and the self-hosting fixpoint is verified on all three operating systems.
* **Standard library:** A growing opt-in stdlib — generics collections, JSON (DOM + parser + writer), SHA-1 and Base64, RFC 4122 UUIDs, TCP sockets, WebSockets, a minimal HTTP/1.1 server, and a `blaise.testing` unit-test framework.


[cols="1,3,1", options="header"]
|===
| Phase | Goal | Status

| 1
| Bootstrap pipeline — Hello World on Linux x86_64 via PasBuild
| Complete ✅

| 2
| Type system — classes, records, ARC, exceptions
| Complete ✅

| 3
| Generics + zero-GUID interfaces
| Complete ✅

| 4
| OPDF debug info emission
| Complete ✅

| 5
| Self-hosting
| Complete ✅

| 6
| Language improvements + expand RTL & StdLib + bug fixing
| Ongoing 🔄

| 7
| Native backend feature parity (default backend, internal assembler + linker)
| Complete ✅

| 8
| FreeBSD x86_64 target — self-hosting fixpoint + full test suite on FreeBSD, bidirectional cross-compilation
| Complete ✅

| 9
| Windows + macOS ARM64 targets
| macOS ARM64 complete ✅ (v0.15.0); Windows planned

| 10
| LSP + VS Code extension
| Planned

| 11
| Migration analyser for FPC/Delphi codebases
| Planned
|===

== What Is Dropped From Classic Pascal

[cols="1,3", options="header"]
|===
| Feature | Reason for removal

| `ShortString`, `AnsiString`, `WideString`, `UnicodeString`
| Replaced by a single UTF-8 reference-counted `string` type

| `with` statement
| Source of hard-to-diagnose symbol resolution bugs; breaks static analysis

| Old-style `object` types
| Use `record` (stack/value) or `class` (heap/reference) instead

| COM-style interface GUIDs
| Interface dispatch via compile-time vtable; GUIDs are unnecessary complexity

| Multiple language modes
| One dialect, maintained well, beats five dialects maintained poorly

| `assign`, `reset`, `rewrite`, `blockread`
| Replaced by a stream-based I/O RTL

| `TObject` vs `TInterfacedObject` split
| One unified class model under automatic reference counting; `[Weak]`
  breaks cycles

| `Extended` (80-bit x87), `Real`, `Comp`, `Currency`
| `Extended` exists only on x86; floats are `Float32` / `Float64`, and
  `Float` is always `Float64`.  `Currency` gives way to a stdlib decimal type.
  `ClassicPascalTypes` maps `Extended` and `Real` to `Float64` for ported code

| Classic integer and float names (`Integer`, `Cardinal`, `LongInt`,
  `SmallInt`, `Word`, `Double`, ...)
| Retired in favour of names that state their width (`Int32`, `UInt32`,
  `Int16`, `UInt16`, `Float64`, ...) and the pointer-sized `Int` / `UInt`.
  They remain available through the opt-in `ClassicPascalTypes` unit;
  BlaiseGuard rule BL-2006 suggests each replacement.  `Byte` stays.
|===

== 📢 Community

The core architecture is still being finalised, so the project is not yet
accepting code contributions. Feedback on language design, syntax choices, and
the future direction of Blaise is very welcome — please use the
https://github.com/graemeg/blaise/discussions[Discussions] tab on GitHub.


== Repository Layout

This project uses PasBuild's multi-module layout. Each subdirectory with a
`project.xml` is an independent module; the root `project.xml` is the aggregator.

....
project.xml                       Root aggregator (packaging=pom)
│
├── compiler/                     The compiler binary (packaging=application)
│   ├── project.xml
│   └── src/
│       ├── main/pascal/          uLexer, uParser, uAST, uSemantic, blaise.codegen.native.*, ...
│       │                         plus the RTL units (runtime.*.pas, rtl.platform.*.pas)
│       └── test/pascal/          Test suite (blaise.testing, compiled by Blaise)
│
├── runtime/                      RTL build module (packaging=library)
│   ├── project.xml
│   └── src/
│       └── test/pascal/          Runtime tests (punit, compiled by Blaise)
│
├── stdlib/                       Standard library — opt-in via uses clause
│   ├── project.xml
│   └── src/
│       ├── main/pascal/          sysutils.pas, classes.pas, math.pas, ...
│       └── test/pascal/          Stdlib tests (blaise.testing, compiled by Blaise)
│
├── tools/
│   └── migration-analyser/       FPC/Delphi migration report tool (packaging=application)
│       ├── project.xml           depends on compiler module
│       └── src/
│           ├── main/pascal/
│           └── test/pascal/
│
└── docs/                         Design documents and specifications
....

PasBuild compiles each module to its own `target/` subdirectory. Build output is
never committed to the repository.

== Building

=== Prerequisites

* A previously released Blaise binary (see `releases/`)
* https://github.com/graemeg/pasbuild[PasBuild] 1.10.1 or later, the build
  tool, installed separately.  Its releases page has prebuilt Linux x86_64
  and macOS arm64 binaries; elsewhere build it from source, which needs
  Free Pascal 3.2.2 or later (FPC builds PasBuild only; it plays no part in
  building Blaise).  On macOS, `scripts/macos-dev.sh` can also be used
  instead (see below).
* No C compiler and no `make`: the compiler builds its RTL from source and
  assembles and links with its own internal assembler and linker.  A C compiler
  is used only when you ask for one with `--assembler external` or
  `--linker external`.

NOTE: FPC is *not* required. Blaise is fully self-hosting — each release binary
compiles the next version. The bootstrap chain starts from the binary in
`releases/`.

=== Bootstrap from a release

Bootstrapping is a single step — the compiler compiles the RTL from source on
demand, so there is no separate runtime build to do first:

[source,shell]
----
# Resolve the newest release binary (substitute the path below for $RELEASE).
RELEASE=$(ls -d releases/v*/ | sort -V | tail -1)blaise   # e.g. releases/v0.12.0/blaise

# Compile the compiler using the release binary (needs no external assembler
# or linker)
$RELEASE \
  --source compiler/src/main/pascal/Blaise.pas \
  --unit-path compiler/src/main/pascal \
  --unit-path stdlib/src/main/pascal \
  --output compiler/target/blaise
----

=== Bootstrap a development checkout

The procedure above works while the latest release binary is new enough to
compile the current source. Between releases that ceases to hold: once a commit
teaches the parser a new feature and a later commit uses it in the
runtime/compiler, the release binary can no longer build `master` directly.

`scripts/rolling-bootstrap.sh` rebuilds the chain commit-by-commit from the last
release binary up to the checked-out revision, producing a working `-pre`
bootstrap binary. See link:scripts/BOOTSTRAP.adoc[scripts/BOOTSTRAP.adoc] for the
prerequisite (placing the release binary under `releases/`) and usage.

=== Build via PasBuild

PasBuild can drive the full compile and test cycle using a Blaise binary:

[source,shell]
----
pasbuild compile -m blaise-compiler --compiler compiler/target/blaise
pasbuild test -m blaise-compiler --compiler compiler/target/blaise
----

PasBuild works the same on macOS.  `scripts/macos-dev.sh` is an
alternative there that drives the compiler directly and needs no PasBuild:

[source,shell]
----
scripts/macos-dev.sh compile     # build compiler/target/blaise
scripts/macos-dev.sh test        # build and run the compiler test suite
----

=== Run tests

[source,shell]
----
pasbuild test -m blaise-compiler --compiler compiler/target/blaise
----

=== Verify self-hosting fixpoint

After any compiler change, verify that the compiler reproduces itself: the
built compiler (stage-1) compiles the compiler into a stage-2 binary, stage-2
compiles it again into stage-3, and the two binaries must be byte-identical:

[source,shell]
----
./scripts/fixpoint-binary.sh --compiler compiler/target/blaise   # BINARY_FIXPOINT_OK
----

`--target <os>-<cpu>` (for example `macos-arm64` or `freebsd-x86_64`)
checks a cross-compiled container instead of the host's.  On macOS,
`scripts/macos-dev.sh fixpoint` runs the same check, and `--install` then
copies the verified stage-2 binary to `compiler/target/blaise`.

The other fixpoint scripts guard narrower paths and are run by hand (CI
runs `fixpoint-binary.sh` on Linux, and the same self-host check on macOS
and FreeBSD).  Each uses the compiler at `compiler/target/blaise` and
prints its `*_OK` marker on success.  They are written to run on Linux,
FreeBSD and macOS (all five pass on macOS arm64).

[cols="2,4,2", options="header"]
|===
| Script | What it checks | Needs

| `fixpoint-binary.sh`
| Stage-2 and stage-3 compiler binaries are byte-identical (the main check;
  CI runs it for the host and for `macos-arm64`).
| The compiler only

| `fixpoint-warmcache.sh`
| Rebuilding the whole compiler against its own cached unit interfaces
  (`--unit-cache`) gives a correct compiler; catches interface
  writer/reader mismatches that a cold build never exercises.
| The compiler only

| `fixpoint-initorder.sh`
| Unit initialisation runs in dependency order however units are split
  between the cache and source.
| The compiler only

| `fixpoint-native.sh`
| Stage-2 and stage-3 emit identical assembly text.
| An external C toolchain (`cc`, or `$CC`) to assemble and link

| `fixpoint-native-internal.sh`
| The internal assembler and linker produce a program that behaves like
  the external toolchain's.
| An external C toolchain (`cc`, or `$CC`) for the reference build
|===

=== Running the compiler

Once built, the compiler binary is at `compiler/target/blaise`.

[source,shell]
----
# Compile a single-file program (no external tools)
compiler/target/blaise --source Hello.pas --output Hello

# Compile with unit search paths
compiler/target/blaise --source MyApp.pas \
  --unit-path src/units \
  --output MyApp

# Print the generated assembly (a debugging aid — no binary is built)
compiler/target/blaise --source Hello.pas --emit-asm
----

[NOTE]
====
`--emit-asm` is a *debugging aid*, not a build step: it prints the generated
assembly and produces no binary.  Always build with
`--output`, which lets the compiler own the whole pipeline.

In particular, do **not** hand-assemble and link that output with `gcc`.  The compiler
compiles the RTL from source on demand into a target-keyed object cache, so a
manual link is both unnecessary and easy to get wrong (it was the cause of
https://github.com/graemeg/blaise/issues/180[issue #180]).

What the compiler *does* need is the RTL source to be reachable — via
`--rtl-src DIR`, `$BLAISE_RTL_SRC`, or a `blaise.cfg` beside the binary (the
release tarballs ship one, so an extracted release works with zero flags).
The binary finds its own directory however it is started: by path, from
`$PATH`, or through a symlink such as `/usr/local/bin/blaise`.

The RTL object cache lives in an `rtl/` directory beside the binary.  When
that directory is not writable (a root-owned install, say), the compiler uses
`$XDG_CACHE_HOME/blaise/rtl`, or `~/.cache/blaise/rtl`, instead.
`--rtl-cache DIR`, `rtl-cache=DIR` in `blaise.cfg` or `$BLAISE_RTL_CACHE`
choose the location explicitly.
====

== Examples

Standalone Blaise projects that show the language, the async/fibre runtime, and
the standard library used in real applications:

* https://github.com/graemeg/blaise-microservice-demo[blaise-microservice-demo] —
  a port of the Java Virtual Threads "API aggregator" demo. An HTTP server whose
  `/aggregate` endpoint fans out three concurrent downstream calls that complete
  in ~2 s wall-clock (not 6 s) via the fibre `TTaskGroup` nursery and the M:N
  scheduler, plus a mini-Gatling load generator that ramps to 6000 concurrent
  virtual users on a handful of OS threads — no framework, no GC. Includes a
  side-by-side Blaise-vs-Java comparison.

* https://github.com/graemeg/luhmann[luhmann] — a
  https://en.wikipedia.org/wiki/Zettelkasten[Zettelkasten] note server. Turns a
  directory of AsciiDoc notes into a linked web of pages served over HTTP, with
  an interactive note graph and a JSON API, rendering the whole collection
  concurrently at start-up.

== Licence

Apache License v2.0 with Runtime Library Exception. See link:LICENSE[LICENSE].


---
*Built with ❤️ for the Pascal community by Graeme.*