# PBXB64 — Pure-C Multi-Language Compiler for Windows x64

PBXB64 is a self-contained compiler toolchain producing PE32+ executables. All frontends (PB/BASIC, PILOT, B64, C, x64 ASM) compile directly through native C17 code — **no Python, no external translators**.

## Native input paths

| Input | Frontend |
|---|---|
| `.b64` | Native B64 frontend → IR → x64 → COFF → PE |
| `.asm`, `.s` | Native x64 assembler → COFF → PE |
| `.pil` | Native PILOT frontend → IR → x64 → COFF → PE |
| `.pb`, `.bas`, `.pba`, `.basic`, `.pbas` | Native PB/BASIC frontend (3710 lines C) → IR → x64 → COFF → PE |
| `.c`, `.h` | Native C17 frontend (4468 lines C) |
| `.obj`, `.lib` | Native linker input |

## V4 validation status (2026-06-12)

Validated from `core/build/PBXB64`, rebuilt from the V4 source tree:

```
PBXB64 version 0.50.0-V6 (Release V6)
```

### Test pass summary

| Category | Pass | Expected fails | Total |
|----------|------|---------------|-------|
| Assembly (-S) | 291 | 0 | 291 |
| PB Link+Run | 92 | 0 | 92 |
| B64 Link+Run | 13 | 0 | 13 |
| C Compile (-S) | 97 | 33 (c_hlib sources without `main()`) | 130 |
| C Link+Run | 2 | 0 | 2 |
| **Total** | **495** | **33** | **528** |

**Zero unexpected fails. Zero regressions. All tests pass for real.**

### Key milestones in V6

| Area | Milestone |
|------|-----------|
| **H-Lib containers** | 22 native container families (`Arr`, `Stk`, `Que`, `Lst`, `Str`, `2D`, `Hsh`, `Tre`, `DTre`, `Tri`, `Heap`, `Deque`, `Set`, `Graph`, `Multiset`, `UnionFind`, `LRU`, `Ring`, `SkipList`, `BPTree`, `Quadtree`, `Bloom`, `Safe`) with auto-init/final and method dispatch. |
| **Container params & returns** | Containers can be passed `BYVAL`/`BYREF` and returned from `FUNCTION`; ownership is moved automatically. 23 per-family regression tests cover every H-Lib family. |
| **Container subscripts** | `a[1]` / `a[1] = x` syntax for indexed/keyed containers; `a[r, c]` for 2D grids. |
| **UDT payloads** | `Arr`, `Lst`, Long-keyed `Hsh`, and Long-keyed `Tre` accept `OF MyType` payloads. |
| **CODEPTR** | `CODEPTR(FunctionName)` now returns the real function address, enabling `Arr.SortUsing CODEPTR(Comparator)`. |
| **C frontend H-Lib parity** | Public C header `core/include/c17/pbxb64/hlib.h` and `examples/c/c_hlib_lnarr.c`. |
| **VARIANT types** | Full `VARIANT` scalar, fixed arrays, dynamic arrays, `VARIANTVT`, `REDIM PRESERVE`, and element-wise lifecycle management. |
| **P0 runtime** | `ERROR$`, `UCODE$` / `UCODEPAGE`, and `PRINT USING` implemented. |
| **Z64 bug sweep** | 25 frontend/backend/diagnostic bugs fixed; all previously-documented limitations cleared. |

### Key milestones in V4

| Area | Milestone |
|------|-----------|
| **H-Lib containers** | All 10 container families (Arr, Stk, Que, Lst, Str, 2D, Hsh, Tre, DTre, Tri) implemented natively — auto-init/final, method dispatch, 12 tests passing |
| **String concat fix** | Fixed `bestof_str_concat` relocation offsets. String concatenation in user-defined functions with BYVAL string params now works correctly. |
| **New types** | Added VARIANT, OBJECT, GUID, STRINGZ, WSTRINGZ type support with runtime stubs. |
| **Debug hooks** | Added `#HOOK` / `#ENDHOOK` debug directive system for variable lifecycle tracing. |
| **Distribution** | V4 release published live at `smart-ai-robot.com/compilers/pbxb64/`. |

### Key milestones in Z64

| Area | Milestone |
|------|-----------|
| **Float FOR** | Fixed 5 latent bugs in float FOR loops (SSE movq ModRM swap, SSE arith ModRM swap, peephole pass 4 imm64 truncation, SETCC partial-write mishandling, PB frontend slot-float const-folding) |
| **FOR/NEXT coverage** | All 7 intlike types (LONG, INTEGER, QUAD, DWORD, WORD, BYTE, CURRENCY), negative STEP, nested 2/3-deep, nested dependent bounds, float FOR |
| **Linker** | All 4 previously-failing PB programs now link cleanly (zero unresolved symbols) |

### Z61 milestones (predecessor)

| Area | Milestone |
|------|-----------|
| **FOR loop** | Fixed "FOR body constant-fold" bug. pb_var_value now never marks slot-backed scalars as const, so `g = g + i` inside a FOR body emits an `add; store` instead of being folded to `store 1`. |
| **Negative STEP** | `FOR i = 10 TO 1 STEP -1` now works for all integer types. |
| **Float FOR** | Added `FOR f = 1.0 TO 3.0` support with float STEP and float compare. (Binary runtime bug for float FOR remained until Z62.) |

## Version

```
PBXB64 version 0.50.0-z64 (Release V4)
```

## Quick start

### Build (Windows + MinGW)

```batch
cd core
build_mingw64.bat
.\build\PBXB64.exe --version
```

### Build (cross-platform via CMake)

```bash
cd core
cmake -S . -B build_cmake -G "MinGW Makefiles"
cmake --build build_cmake
```

### Build (native Linux/macOS, compiler validation only)

```bash
cd core
cmake -S . -B build_native -G "Unix Makefiles"
cmake --build build_native
# Excludes Win32 runtime units that require Windows headers.
```

### Compile a PB program

```batch
.\build\PBXB64.exe examples\basic\for_int_basic.pb -o for_int_basic.exe
.\for_int_basic.exe
echo %ERRORLEVEL%
```

### Compile a B64 program

```batch
.\build\PBXB64.exe examples\b64\answer.b64 -o answer.exe
.\answer.exe
```

### Compile a C program

```batch
.\build\PBXB64.exe -std=c17 examples\c\simple.c -o simple.exe
.\simple.exe
```

### Run the full test lane

```powershell
cd core
.\run_pb_tests.ps1                # build + test
.\run_pb_tests.ps1 -SkipBuild     # test only
```



## Language Coverage Highlights

### PB/BASIC (native pb_frontend.c)
- Type suffixes: $, %, &, !, #, ##, ??
- Literal prefixes: &H, &O, &B
- %Equates / $EQUATE / MACRO / MACROFUNCTION
- #COMPILE, #INCLUDE ONCE, #DEFINE, #IF/#ELSEIF/#ELSE/#ENDIF
- BYTE/WORD/DWORD/QWORD/QUAD/LONGINT/BOOL types
- SINGLE/DOUBLE runtime variables; WSTRING, PTR types; ENUM/UNION lowering
- BYREF/OPTIONAL parameters; DECLARE LIB/ALIAS with ordinal imports
- Control: IF/SELECT CASE (ranges, IS / TO), FOR/WHILE/DO, EXIT/ITERATE, GOSUB/RETURN, ON GOTO/GOSUB
- DATA/READ/RESTORE, PRINT USING, FORMAT$, CONSOLE I/O (INPUT, LINE INPUT)
- Dynamic arrays: DIM/REDIM/REDIM PRESERVE/ERASE, LBOUND/UBOUND
- Strings: builtins documented in pb_frontend.c (REPEAT$, STRDELETE$, REPLACE$, TALLY, etc.)
- File I/O: OPEN/CLOSE/GET/PUT/SEEK/LOF/EOF/FREEFILE, PRINT#/INPUT#/LINE INPUT#
- Memory: PEEK/POKE/VARPTR/STRPTR/ALLOCATE/REALLOCATE/FREE
- Math builtins: SQR/SIN/COS/EXP/LOG, RND/RANDOMIZE, MIN/MAX/IIF/CHOOSE
- DLL export: #COMPILE DLL, EXPORT FUNCTION/SUB → .edata
- Inline #ASM with 58 register names, ~50 new instructions
- Runtime: c_runtime.c (string/console/math helpers, embedded in PBXB64)

### C (native c_frontend.c)
- Full C17 lexer/preprocessor: `#include`, `#define` (object + function-like), `#if`/`#ifdef`/`#elif`/`#else`/`#endif`, `#error`, `##` token pasting
- CLI: `-I`, `-D`, `-U`, `-E`, `-std=c89/c90/c99/c11/c17/c18` and GNU aliases, `-Wall`/`-Wextra`/`-Werror`
- Control flow: `if`/`else`, `while`, `for`, `do-while`, `switch`/`case`/`default`, `goto`/labels, `break`/`continue`
- Expression parser: full precedence, constant folding, casts, `sizeof`, runtime ternary
- Struct member access: `.` / `->` implemented in parser
- 29 C17 headers under `core/include/c17/`

**Z56 note:** C frontend correctness continues to improve. Flexible array member false positive fixed for enum constant array sizes; array size expressions now evaluate macro constants. Full hosted C99 completeness is still not claimed.

### PILOT (native pilot_frontend.c)
- Full standalone PILOT compiler (`-o` produces PE directly)
- Support statements: SET, MATCH, TRANSLATE, ACCEPT, APPEND, CHANGE, COMPUTE, COPY, EXEC, FETCH, FLOAT, IDENTIFY, INT, IS, JOIN, LINK, MARK, NEGATE, NOTE, RESET, SCAN, SIZE, STACK, TRACE, TRANSFORM, TYPE, USE

## Documentation

| File | Description |
|---|---|
| `AGENTS.md` | Full project documentation for AI agents |
| `core/README.md` | Core compiler details |
| `VALIDATION.md` | Validation status |
| `FEATURES_ADDED.md` | Feature additions log |
| `BASIC_IMPLEMENTATION_STATUS_2026-04-03.md` | PB/BASIC implementation status |
