PBXB64 - Overview

PBXB64 Compiler V9 Documentation

Version: 0.9.0-native (C17 Hardening)
Target: Windows x64 PE32+ executables
Tests: 72/72 smoke tests passing
License: Free for private use
Copyright: © 2026 Theo Gottwald / www.smart-package.com

Language Frontends

Language | Extensions | Status | Description
B64 | .b64 | Active | C-like systems language. Primary frontend with full IR integration.
BASIC | .pb, .bas, .pba | Growing | PowerBASIC-compatible dialect. V8 supports PRINT, STRING, control flow, WinAPI calls.
C Subset | .c | Growing | Controlled C17 subset. V9 adds full preprocessor hardening, function pointers, runtime aliases.
Assembly | .asm, .s | Active | Native x64 assembler with Intel syntax. Direct COFF/PE output.
PILOT | .pil | Active | Educational language (Atari-style). T:, A:, M:, Y:, N:, C:, J:, U:, E:, R:, S:, D: commands.

Compiler Pipeline

Source (.b64/.pb/.c/.asm/.pil)
  |-> Per-language Lexer + Parser -> AST
  |-> IR Builder (unified intermediate representation)
  |-> Middle-end (CFG, dominance, pass manager, optimizer)
  |-> x64 CodeGen (register allocation, instruction selection)
  |-> Assembler (x64 encoding, COFF emission)
  |-> PE Linker (import table, relocations, PE32+ image)

V9 Highlights

  • Preprocessor Hardening: _Pragma, #pragma, #line, __FILE__, __LINE__
  • Extended #if Evaluator: Supports + - * / % << >> & ^ | operators
  • Function Pointers: Simple direct calls via local function pointer initialization
  • Runtime Aliases: malloc, free, strlen mapped to native/KERNEL32 implementations
  • Header Strengthening: Full prototypes for string.h, stdlib.h, stdio.h
  • Struct/Union Shells: Parsing and layout coverage for bitfields and aggregates
  • Mixed Language Linking: Preserved B64 + C interoperability with V9 runtime

Documentation Sections

  • Command-Line Options -- All compiler flags and switches
  • B64 Language Reference -- The primary systems language
  • BASIC Language Reference -- PowerBASIC-compatible syntax
  • C Language Reference -- C17 subset with preprocessor & V9 hardening
  • Assembly Reference -- Native x64 assembler
  • PILOT Language Reference -- Educational language
  • Example Programs -- Sample code for all languages
Next: CLI Options → Language Frontends Overview View Examples
PBXB64 Compiler Documentation · V9 Native Edition · Last updated 2026-01-15
For issues and contributions: smart-package.com


PBXB64 - Assembly Language Reference

Assembly Language Reference (Native x64)

PBXB64 includes a native x64 assembler that accepts Intel-syntax assembly and produces COFF objects or PE executables directly. No external assemblers required.

Supported Extensions

.asm and .s files are automatically routed through the native x64 assembler pipeline.

Basic Structure

section .text
global main

main:
    push rbp
    mov rbp, rsp
    mov eax, 42
    pop rbp
    ret

Assembler Pipeline

.asm / .s  →  ASM Lexer  →  ASM Parser  →  Encoder  →  COFF Object  →  PE Linker

Data Sections & Variables

section .data
msg: db "Hello, World!", 0
len: equ $ - msg

section .bss
buffer: resb 1024

section .text
global main
main:
    lea rcx, [rel msg]
    call printf
    ret

Integration with Other Frontends

Assembly files can be linked seamlessly with B64, BASIC, and C object files using the PE linker:

PBXB64 main.b64 helper.asm -o program.exe
PBXB64 prog.c utils.s -o mixed.exe

Syntax Notes

  • Intel syntax: instruction destination, source
  • Registers: rax, rbx, rcx, rdx, rsi, rdi, rsp, rbp, r8-r15
  • Modes: 64-bit (default), 32-bit (rax → eax, etc.)
  • Immediate values: decimal (42), hex (0x2A), octal (0o52)
Performance Tip: Use -O2 or higher when linking assembly with high-level code to enable cross-language inlining and register optimization.
← C Reference PILOT Reference → View Examples
PBXB64 Compiler Documentation · V8 Native Edition · Last updated 2026-01-15


PBXB64 - B64 Language Reference

B64 Language Reference

B64 is a C-like systems programming language and the primary frontend of PBXB64. It features explicit memory management, first-class pointers, structs, and direct IR integration.

Function Syntax

fn name(params): return_type { body }
fn add(a: i32, b: i32): i32 {
    return a + b;
}

fn main(): i32 {
    let result: i32 = add(10, 20);
    return result;
}

Primitive Data Types

Type | Size | Description
i8 | 1 byte | Signed 8-bit integer (-128 to 127)
i16 | 2 bytes | Signed 16-bit integer
i32 | 4 bytes | Signed 32-bit integer (default int)
i64 | 8 bytes | Signed 64-bit integer
u8 | 1 byte | Unsigned 8-bit integer (0 to 255)
u16 | 2 bytes | Unsigned 16-bit integer
u32 | 4 bytes | Unsigned 32-bit integer
u64 | 8 bytes | Unsigned 64-bit integer
bool | 1 byte | Boolean (true/false)
f32 | 4 bytes | IEEE 754 single-precision float
f64 | 8 bytes | IEEE 754 double-precision float

Pointers & Dereferencing

let p: *type = &variable;
fn main(): i32 {
    let x: i32 = 42;
    let p: *i32 = &x;
    *p = 100;       // dereference write
    return *p;      // dereference read -> 100
}

Structs

struct Point {
    x: i32,
    y: i32,
}

fn main(): i32 {
    let p: Point = Point { x: 10, y: 20 };
    return p.x + p.y;
}

Control Flow

// Conditional
if condition { body } else { body }

// Looping
while expr { body }
for let i: i32 = start; i < end; i = i + step { body }

// Return
return expression;
return; // void return

External Functions (FFI)

extern "kernel32.dll" fn Sleep(dwMilliseconds: u32): void;
extern "user32.dll" fn MessageBoxA(hWnd: *void, lpText: *u8, lpCaption: *u8, uType: u32): i32;
Memory Model: B64 uses explicit allocation via alloc/dealloc intrinsics. Stack variables are automatic. Pointers must be validated before dereferencing in safe mode.
← CLI Options BASIC Reference → View Examples


PBXB64 - BASIC Language Reference

BASIC Language Reference (PowerBASIC-Compatible)

PBXB64 supports a growing PowerBASIC-compatible dialect. V8 strengthens string lifetime management, PRINT semantics, and WinAPI integration.

Program Entry Point

FUNCTION PBMAIN() AS LONG ... END FUNCTION
FUNCTION PBMAIN() AS LONG
    FUNCTION = 0   ' Return code
END FUNCTION

Variable Declarations

LOCAL x AS LONG          ' Stack variable
LOCAL s AS STRING        ' Heap-managed string
LOCAL f AS SINGLE        ' 32-bit float
DIM arr(10) AS LONG      ' Static array (0-10)
GLOBAL g AS LONG         ' Module-level global

Assignment & Operators

x = 42
s = "Hello World"
x = x + 1
y = a * b - c / d
z = (x > 0) AND (y < 10)

PRINT Statement

PRINT expr [; expr] [, expr]
PRINT "Hello"
PRINT "A"; "B"       ' Semicolon: no separator
PRINT "A", "B"       ' Comma: tab stop (~8 chars)
PRINT TAB(4); "D"    ' TAB(n): pad with spaces

Control Flow

' IF/THEN/ELSE
IF x > 0 THEN
    PRINT "positive"
ELSE
    PRINT "negative"
END IF

' FOR/NEXT
FOR i = 1 TO 10 STEP 2
    PRINT i
NEXT i

' WHILE/WEND
WHILE x < 100
    x = x * 2
WEND

WinAPI Integration

#INCLUDE "windows_core.pbi"

FUNCTION PBMAIN() AS LONG
    CALL MessageBoxA(0, "Hello", "PBXB64", 0)
    CALL Sleep(1000)
    FUNCTION = 0
END FUNCTION

String Operations (V7/V8)

LOCAL s AS STRING, t AS STRING
s = "Hello"
t = s + " World"     ' Concatenation
s = ""               ' Reassignment frees old heap string automatically
s = LEFT$(t, 5)      ' Built-in string functions
String Lifetime Management: V7/V8 automatically frees heap-backed STRING values on reassignment, before RETURN, EXIT FUNCTION, and natural function exit. No manual STRFREE needed.

Known Limitations (V8)

  • VARPTR currently supported for arrays only (scalar VARPTR deferred)
  • Struct field access (obj.field) not yet lowered in this pass
  • &H hex literals not yet supported
  • FULL PowerBASIC compatibility is ongoing work
← B64 Reference C Language Reference → View Examples


PBXB64 - C Language Reference (C17 Subset)

C Language Reference (C17 Subset)

PBXB64 supports a controlled C17 subset interoperable with B64/PB/PILOT through the unified IR. V8 adds full preprocessor, runtime control flow, and 26 standard headers. V9 hardens preprocessor corner cases, adds function pointers, and strengthens runtime aliases.

Preprocessor (V8/V9 Full Support)

V8/V9 adds complete C preprocessor support
#define MAX 100
#define ADD(a,b) ((a)+(b))

#if MAX > 50
    int x = 1;
#elif defined(DEBUG)
    int x = 2;
#else
    int x = 3;
#endif

#ifdef __STDC__
    int ver = __STDC_VERSION__;  // 201710L
#endif

// Stringification and token paste
#define STR(x) #x
#define CAT(a,b) a##b
Directive | V8/V9 Support
#define / #undef | Object-like and function-like macros
#if / #ifdef / #ifndef | Full expression evaluation (+ - * / % << >> & ^ |)
#elif / #else / #endif | Nested conditionals
#include | Local and system headers
#error | Diagnostic messages
# / ## | Stringification and token paste
Variadic macros | __VA_ARGS__
_Pragma / #pragma | Accepted/ignored, stripped during expansion (V9)
#line | Compatibility directive accepted (V9)
__FILE__ / __LINE__ | Predefined string/integer macros (V9)

C17 Standard Headers (V8/V9)

26 C17 headers available at core/include/c17/. Include with -I flag:

PBXB64 -I core/include/c17 program.c -o program.exe
stdio.h | stdlib.h | string.h | stdint.h
stddef.h | stdbool.h | stdalign.h | stdarg.h
limits.h | float.h | math.h | ctype.h
assert.h | errno.h | time.h | inttypes.h
fenv.h | iso646.h | locale.h | setjmp.h
signal.h | stdatomic.h | stdnoreturn.h | threads.h
tgmath.h | wchar.h | wctype.h | uchar.h

V9 Runtime & Function Pointers

V9 adds native runtime aliases and simple function-pointer calls:
// Simple direct function pointer call (V9)
long long add(long long a, long long b) { return a + b; }
int main(void) {
    long long (*fp)(long long, long long) = &add;
    return (int)fp(20, 22);
}

// Runtime aliases (V9)
void* p = malloc(100);   // Maps to KERNEL32 HeapAlloc
free(p);                 // Maps to KERNEL32 HeapFree
size_t len = strlen(s);  // Native bestof implementation

Control Flow (V8)

// switch/case with fallthrough
switch (x) {
    case 1: do_something(); break;
    case 2:
    case 3: do_other();    // intentional fallthrough
        break;
    default: break;
}

// goto/labels
if (x) goto label;
label: return 0;

// ternary operator
return (x > 0) ? 1 : -1;

// multi-increment for loop
for (int i = 0; i < 10; i++, j += 2) {
    body
}

Language Features (V8/V9)

Feature | Status
_Static_assert | Integer constant expressions
_Alignof | Bootstrap handling
sizeof | Type and expression forms
union | Parsing and layout (V9 shell)
Function pointer typedefs | Declarations, address-of, direct calls (V9)
Bitfield-bearing structs | Bodies parsed/skipped safely (V9)
Octal integer constants | Supported
Adjacent string literals | Covered cases
Backslash-newline splicing | Preprocessor phase
Known C17 Gaps: Not full hosted C17. No windows.h, no complete floating-point guarantee, no varargs ABI/runtime (planned V11), no indirect function-pointer calls beyond local direct targets, no complex/atomics/threads/fenv depth.
← BASIC Reference Assembly Reference → View Examples
PBXB64 Compiler Documentation · V8/V9 Native Edition · Last updated 2026-01-15


PBXB64 - Command-Line Options

Command-Line Options Reference

PBXB64 [options] <input files>

Output Control

Option | Description
-o <file> | Set output executable path (default: a.exe)
-c | Compile only – produce object file (.obj), skip linking
-S | Stop after assembly generation (.asm)
--emit-ast | Emit AST dump to stdout for debugging
--emit-ir | Emit IR dump to stdout
--emit-asm | Emit assembly listing to stdout
--emit-obj | Force object file emission (alias for -c)

Preprocessor (V8 Enhanced)

Option | Description
-E | Preprocess only – output expanded source to stdout
-I <path> | Add user include search path (checked first)
-isystem <path> | Add system include path (suppresses warnings)
-DNAME | Define macro NAME=1
-DNAME=value | Define macro with explicit value
-UNAME | Undefine previously defined macro
-std=c17 | Enable C17 standard mode (default in V8)
-ffreestanding | Freestanding environment (no runtime dependencies)

Optimization Levels

Option | Description
-O0 | No optimization (default, fastest compile, debug-friendly)
-O1 | Basic optimizations: dead code elimination, constant folding
-O2 | Aggressive: inlining, loop unrolling, register allocation tuning
-O3 | Maximum optimization (may increase binary size)

Target & General Options

Option | Description
--target <triple> | Set target triple (default: x86_64-pc-windows-msvc)
--entry <symbol> | Override default entry point symbol
-v, --verbose | Verbose output – show compilation steps and paths
--version | Print compiler version and exit
V8 Tip: Combine -E -I core/include/c17 -DDEBUG=1 program.c to inspect preprocessed output with custom macros and headers.
← Overview B64 Language Reference → View Examples


PBXB64 - Example Programs

Example Programs & Quick Start Guide

Complete, compilable examples for each language frontend. All examples target Windows x64 PE32+ executables.

B64 - Hello World

fn main(): i32 {
    return 42;
}
PBXB64 hello.b64 -o hello.exe

B64 - Pointers & Structs

struct Point { x: i32, y: i32 }

fn main(): i32 {
    let p: Point = Point { x: 10, y: 20 };
    let q: *Point = &p;
    q.x = 30;
    return q.x + q.y;  // Returns 50
}

BASIC - Console Output

FUNCTION PBMAIN() AS LONG
    PRINT "Hello from PBXB64!"
    PRINT "Answer:"; 42
    FUNCTION = 0
END FUNCTION

BASIC - WinAPI Integration

#INCLUDE "windows_core.pbi"

FUNCTION PBMAIN() AS LONG
    CALL MessageBoxA(0, "Hello", "PBXB64", 0)
    FUNCTION = 0
END FUNCTION

C - Standard I/O & Preprocessor

#include <stdio.h>
#define VERSION "V8"

int main(void) {
    printf("Hello from C %s\n", VERSION);
    return 0;
}
PBXB64 -I core/include/c17 -std=c17 program.c -o program.exe

C - Runtime Control Flow

int main(void) {
    int x = 2;
    switch (x) {
        case 1: return 10;
        case 2: return 20;  // Falls through to default if break missing
        default: return 0;
    }
}

PILOT - Interactive Quiz

T: What is 2+2?
A:
M: 4
Y: Correct! Well done.
N: Try again...
E:

Mixed B64 + C Linking

// sum.c
int add(int a, int b) { return a + b; }

// main.b64
fn main(): i32 {
    extern "sum.c" fn add(a: i32, b: i32): i32;
    return add(10, 20);  // Returns 30
}
PBXB64 main.b64 sum.c -o mixed.exe
Pro Tip: Use --emit-ir or --emit-ast to debug compilation issues. Combine -v for verbose step-by-step output.
← PILOT Reference Back to Overview CLI Options →


PBXB64 - Language Frontends

Language Frontends Overview

PBXB64 features five distinct language frontends that compile through a unified IR and x64 backend. Each frontend is optimized for its target use case while maintaining cross-language interoperability.

B64 (Primary Systems Language)

C-like syntax with manual memory management, explicit pointers, and first-class structs. Designed for systems programming where performance and control are paramount.

fn main(): i32 {
    let x: i32 = 42;
    let p: *i32 = &x;
    *p = 100;
    return x;
}

BASIC (PowerBASIC-Compatible)

Modernized PowerBASIC dialect with V8 string lifetime management, PRINT separator semantics, and native WinAPI integration.

FUNCTION PBMAIN() AS LONG
    LOCAL s AS STRING
    s = "Hello from PBXB64"
    PRINT s
    FUNCTION = 0
END FUNCTION

C Subset (C17 with Preprocessor)

Controlled C17 subset featuring full preprocessor, switch/case/goto, ternary operator, and 26 standard library headers.

#include <stdio.h>
int main(void) {
    printf("Hello from C\n");
    return 0;
}

Assembly (Native x64)

Intel-syntax assembler with direct COFF/PE output. Supports .asm/.s files and integrates seamlessly with high-level frontends.

section .text
global main
main:
    mov eax, 42
    ret

PILOT (Educational)

Atari-style interactive language for teaching programming concepts. Supports T:, A:, M:, Y:, N:, C:, J:, U:, E:, R:, S:, D: commands.

T: Hello from PILOT!
A: What is your name?
T: Nice to meet you!
E:
Cross-Language Linking: All frontends compile to the same IR and can be linked together. Mix B64, C, BASIC, and Assembly in a single project.
← Overview B64 Reference → View Examples
PBXB64 Compiler Documentation · V8 Native Edition · Last updated 2026-01-15


PBXB64 - PILOT Language Reference

PILOT Language Reference (Educational)

PILOT is an interactive educational programming language inspired by the classic Atari/PLATO system. PBXB64 supports standalone .pil files and inline #PCODE blocks in BASIC programs.

Core Commands

Command | Description
T: | Type (print) text to output
A: | Accept (read) input from user into $answer
M: | Match input against pattern, sets match variables
Y: | Yes - execute next line if match succeeded
N: | No - execute next line if match failed
C: | Compute (assign variable or expression)
J: | Jump to labeled line
U: | Use (call subroutine at label)
E: | End (return from subroutine or terminate program)
R: | Remark (comment line, ignored by interpreter)
S: | Sound (generate system beep)
D: | Dimension (declare array/table)

Standalone .pil Example

T: Welcome to PILOT!
A: What is your name?
T: Hello, $answer! Nice to meet you.
C: age = 10 + 5
T: In five years you will be $age.
E:

Embedded #PCODE Block

#COMPILE EXE "program.exe"
#DIM ALL

FUNCTION PBMAIN() AS LONG
    #PCODE
    T: Interactive Quiz Mode
    A: What is 2 + 3?
    M: 5
    Y: Correct! Well done.
    N: Try again next time.
    E:
    #ENDP
    FUNCTION = 0
END FUNCTION

Match Variables (Auto-Set by M:)

Variable | Description
$answer | Last accepted input string
$match | The portion of $answer that matched the pattern
$left | Text before the match in $answer
$right | Text after the match in $answer
#pos | Starting position of match (0-based)
Educational Use: PILOT is ideal for teaching conditional logic, string matching, and interactive program flow. Combine with BASIC for hybrid educational tools.
← Assembly Reference View Examples → Back to Overview