PBXB64 Compiler — Installation & Quick Start
==============================================

Version: 0.50.0-z64  (2026-06-11)
Target:  Windows 10/11 x64


1. REQUIREMENTS
---------------

- Windows 10 64-bit or newer
- ~50 MB free disk space
- No third-party tools required (PBXB64 is fully self-contained)


2. INSTALLATION
---------------

2.1 From a release ZIP (recommended for end users)
---------------------------------------------------

  1. Extract PBXB64_V64_Release.zip to any folder, e.g. C:\PBXB64\
  2. Verify the binary is signed:
     - Right-click core\build\PBXB64.exe -> Properties -> Digital Signatures
     - Signer must be: Theo Gottwald
     - If signature is missing or invalid, DO NOT USE the file.
  3. Add C:\PBXB64\core\build\ to your PATH (optional)
  4. Done. No registry edits, no installer required.

2.2 From source (developers)
----------------------------

  1. Install MinGW-w64 (any recent version, e.g. via MSYS2 or WinLibs)
  2. Open a MinGW shell in the repo root
  3. Build:
       cd core
       mingw32-make -f Makefile.mingw -j4
       .\build\PBXB64.exe --version
     You should see: "PBXB64 version 0.50.0-z64"

  4. Run the test suite:
       .\run_pb_tests.ps1
     You should see all 298 tests pass with 0 expected fails.


3. WRITING YOUR FIRST PROGRAM
-----------------------------

3.1 PB (PowerBASIC-compatible) BASIC
-------------------------------------

Save as hello.pb:

    FUNCTION PBMAIN() AS LONG
        PRINT "Hello from PBXB64!"
        PBMAIN = 0
    END FUNCTION

Compile and run:

    PBXB64 hello.pb -o hello.exe
    hello.exe


3.2 B64 (the native B64 systems language)
-----------------------------------------

Save as hello.b64:

    function main() {
        print("Hello from B64!\n");
        return 0;
    }

Compile and run:

    PBXB64 hello.b64 -o hello.exe
    hello.exe


3.3 C (C17 subset)
------------------

Save as hello.c:

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

Compile and run:

    PBXB64 -std=c17 hello.c -o hello.exe
    hello.exe


3.4 Inline x64 assembly
-----------------------

Save as hello.asm:

    section .text
    global main
    main:
        sub rsp, 28
        lea rcx, [msg]
        call printf
        xor eax, eax
        add rsp, 28
        ret
    section .rdata
    msg: db "Hello from PBXB64 ASM!", 0

Compile and run:

    PBXB64 hello.asm -o hello.exe
    hello.exe


4. COMMAND-LINE OPTIONS
-----------------------

    PBXB64 [options] <input files>

    -o <file>            Output file path
    -c                   Compile to .obj (do not link)
    -S                   Stop after code generation, emit .asm
    -fsyntax-only        Check syntax, no codegen
    --emit-ir            Emit IR text and stop
    --emit-mir           Emit MIR (machine IR) dump
    --emit-asm           Emit assembly dump
    --emit-obj           Emit object file
    --target <triple>    Target triple (default: x86_64-windows-msvc)
    --entry <symbol>     Entry point symbol (default: main or PBMAIN)
    -O0 .. -O3           Optimization level
    -v, --verbose        Verbose output
    --version            Print version info
    -E                   Preprocess C input only
    -std=<mode>          C standard: c89, c99, c11, c17, gnu*
    -I <path>            Add C include path
    -D NAME[=VALUE]      Define C preprocessor macro
    -U NAME              Undefine C preprocessor macro


5. FOR/NEXT SUPPORT
-------------------

PBXB64 supports the full PB FOR/NEXT specification:

  Integer types:   LONG, INTEGER, QUAD, DWORD, WORD, BYTE, CURRENCY
  Float types:     SINGLE, DOUBLE (and FLOAT/EXTENDED in source)
  STEP:            positive, negative, default +1 / +1.0

Examples:

    FOR i = 1 TO 10
        ' body
    NEXT

    FOR i = 10 TO 1 STEP -1
        ' reverse iteration
    NEXT

    FOR f = 1.0 TO 3.0
        ' float iteration
    NEXT

    FOR i = 1 TO 3
        FOR j = 1 TO 4
            ' nested
        NEXT
    NEXT


6. SUPPORTED FRONTENDS
----------------------

  .b64, .bas, .pba, .basic, .pbas
  .pb                PowerBASIC-compatible BASIC
  .c, .h             C17 subset (no hosted libc, but full C99 math)
  .asm, .s           x64 assembly (Intel and AT&T syntax)
  .pil               PILOT educational language

For full language feature listings, see:
  - AGENTS.md         (project overview for AI agents)
  - FEATURES.md       (detailed feature matrix)
  - core/README.md    (compiler internals)


7. LEGAL
--------

Copyright (c) 2026 Theo Gottwald. Free for private/educational use.

PBXB64.exe MUST be digitally signed by Theo Gottwald.
If signature is invalid, do NOT use the file.

Contact: Theo Gottwald, 76706 Dettenheim, Germany
E-Mail: info@it-berater.org
Web:    smart-package.com


8. WHAT'S NEW IN Z64
--------------------

Bug fixes:
  - Float FOR loops now work (5 separate bugs fixed in one go)
  - All 4 previously-failing PB programs now link cleanly
  - 25 compiler bugs fixed (see ToDo.md for full list)
  - FOR loop test coverage extended: 7 int types, neg STEP, nested 2/3-deep,
    nested dependent bounds, float

Test results: 298/298 pass, 0 expected fails, 0 regressions.

See AGENTS.md for the full changelog.
