X-Code: examples explained

X-Code is a typed assembler dialect inside BASIC. Virtual registers describe values; the compiler assigns physical registers. Memory operations specify their width explicitly.

Twelve short examples and one larger program. Choose a topic or work through the examples in order.

New control-flow and allocation cases refer to the V22 source state; final V22 execution remains pending.

1. 1 + 2 + 3 + 4 + 5 = 15

The numbers 1 through 5 are added to 15. Return value 15 is checked as the process exit code.

#COMPILE EXE
#DIM ALL
FUNCTION PBMAIN() AS LONG
    LOCAL total AS LONG
    #XCODE
        X.VREG sum:U64
        X.MOVE V(sum), 1
        X.ADD V(sum), 2
        X.ADD V(sum), 3
        X.ADD V(sum), 4
        X.ADD V(sum), 5
        X.STORE QWORD PTR [total], V(sum)
    #ENDX
    FUNCTION = total
END FUNCTION

Expected exit code: 15

PBXB64.exe sum15-xcode.pb -O2 -o example.exe
.\example.exe
$LASTEXITCODE

Download source

Executed natively with the V22 candidate from 2026-09-30; final-compiler verification pending.

2. A custom XCODE macro and a BASIC value

The definition section creates X.vendor.ADD5. PBMAIN starts host_value at 7; the macro adds 5 and X.STORE writes back 12. PBMAIN returns host_value - 12, yielding 0 when correct. X.LOCAL keeps the label local to the macro.

' XCODE first-release integration: typed virtual registers lower to the
' existing inline-ASM stub/object pipeline and execute without XCODE text.
#COMPILE EXE
#DIM ALL
GLOBAL host_value AS LONG

#XCODE MODE=DEFINITIONS
    X.MACRO X.vendor.ADD5(INOUT dst:U32)
        X.ADD $dst, 5
        X.LOCAL done:LABEL
        X.RAW
            jmp $done
        $done:
        X.ENDRAW
    X.ENDMACRO
#ENDX

FUNCTION PBMAIN() AS LONG
    host_value = 7
    #XCODE OPT=2, SPILL=AUTO, FEATURES=AUTO
        X.VREG value:U32
        X.MOVE V(value), %host_value
        X.vendor.ADD5 V(value)
        X.STORE %host_value, V(value)
        X.RAW
            nop
        X.ENDRAW
    #ENDX
    PBMAIN = host_value - 12
END FUNCTION

Expected exit code: 0

PBXB64.exe test_xcode.pb -O2 -o example.exe
.\example.exe
$LASTEXITCODE

Download source

Canonical test case with an expected result; no new native V22 check here. Final execution pending.

3. Keep a constant under register pressure

This case avoids the listed physical registers and requests AUTO/SPILL=AUTO. Value 7 must still reach remat_result. The test targets safe constant rematerialization, not a general performance promise. The global LONG slot starts at zero; DWORD writes its lower 32 bits.

' XCODE AUTO rematerializes a safe integer constant instead of spill traffic.
#COMPILE EXE
#DIM ALL
GLOBAL remat_result AS LONG

FUNCTION PBMAIN() AS LONG
    #XCODE REGALLOC=AUTO, SPILL=AUTO
        X.VREG constant:U32
        X.ALLOC AVOID V(constant), r10, r11, r8, r9, rax, rcx, rdx, rdi, rsi, rbx, rbp, r12, r13, r14, r15
        X.MOVE V(constant), 7
        X.STORE DWORD PTR [remat_result], V(constant)
    #ENDX
    IF remat_result <> 7 THEN
        PBMAIN = 1
        EXIT FUNCTION
    END IF
    PBMAIN = 0
END FUNCTION

Expected exit code: 0

PBXB64.exe test_xcode_regalloc_constant.pb -O2 -o example.exe
.\example.exe
$LASTEXITCODE

Download source

Canonical test case with an expected result; no new native V22 check here. Final execution pending.

4. Pin one register and exclude another

Step-by-step flow

REGALLOC=MANUAL selects the explicitly declared allocation policy.
PIN requests r12 for acc; AVOID prevents tmp from using it.
X.ZERO initializes both values. The DWORD store writes 32 bits of the zero-initialized LONG slot; exit code 0 checks completion of this allocation case.

' XCODE manual allocation policy regression.
#COMPILE EXE
#DIM ALL
GLOBAL manual_result AS LONG

FUNCTION PBMAIN() AS LONG
    #XCODE REGALLOC=MANUAL
        X.VREG acc:U64
        X.VREG tmp:U64
        X.ALLOC PIN V(acc), r12
        X.ALLOC AVOID V(tmp), r12
        X.ZERO V(acc)
        X.ZERO V(tmp)
        X.STORE DWORD PTR [manual_result], V(tmp)
    #ENDX
    PBMAIN = 0
END FUNCTION

Expected exit code: 0

PBXB64.exe xcode-test_xcode_regalloc_manual.pb -O2 -o example.exe
.\example.exe
$LASTEXITCODE

Download source

Expectation derived from source; no current registered execution contract. This website expansion adds no new native compiler verification. Execution with the qualified final compiler remains pending.

5. State a register preference

Step-by-step flow

preferred is a virtual U32 value.
PREFER names r12 as the preferred physical register; a preference is not a universal guarantee about emitted assembly.
X.ZERO and the DWORD store produce a stored zero. This example demonstrates preference syntax.

' XCODE manual preference regression.
#COMPILE EXE
#DIM ALL
GLOBAL prefer_result AS LONG
FUNCTION PBMAIN() AS LONG
    #XCODE REGALLOC=MANUAL
        X.VREG preferred:U32
        X.ALLOC PREFER V(preferred), r12
        X.ZERO V(preferred)
        X.STORE DWORD PTR [prefer_result], V(preferred)
    #ENDX
    PBMAIN = 0
END FUNCTION

Expected exit code: 0

PBXB64.exe xcode-test_xcode_regalloc_prefer.pb -O2 -o example.exe
.\example.exe
$LASTEXITCODE

Download source

6. Conflicting register requests

Step-by-step flow

left and right are separate virtual U32 values whose PIN requests name the same register.
Both values are defined and used by X.ADD; the compiler must preserve their separate logical values.
The allocation-check script checks translation and allocation reports; native program execution remains pending here. It does not establish an optimal physical assembly solution.

' XCODE conflicting PIN requests must be remapped safely.
#COMPILE EXE
#DIM ALL
GLOBAL remap_result AS LONG

FUNCTION PBMAIN() AS LONG
    #XCODE REGALLOC=MANUAL
        X.VREG left:U32
        X.VREG right:U32
        X.ALLOC PIN V(left), r12
        X.ALLOC PIN V(right), r12
        X.ZERO V(left)
        X.ZERO V(right)
        X.ADD V(right), V(left)
        X.STORE DWORD PTR [remap_result], V(right)
    #ENDX
    PBMAIN = 0
END FUNCTION

Expected exit code: 0

PBXB64.exe xcode-test_xcode_regalloc_remap.pb -O2 -o example.exe
.\example.exe
$LASTEXITCODE

Download source

7. A memory address as a PTR value

Step-by-step flow

address has pointer type PTR; AVOID restricts available physical registers.
X.LEA forms the global LONG slot's address without reading its contents.
X.STORE QWORD writes the 64-bit address into that eight-byte slot. The numeric address varies between process runs.

#COMPILE EXE
#DIM ALL
GLOBAL address_result AS LONG
FUNCTION PBMAIN() AS LONG
    #XCODE REGALLOC=AUTO
        X.VREG address:PTR
        X.ALLOC AVOID V(address), r10, r11, r8, r9, rax, rcx, rdx, rdi, rsi, rbx, rbp, r12, r13, r14, r15
        X.LEA V(address), BYTE PTR [address_result]
        X.STORE QWORD PTR [address_result], V(address)
    #ENDX
    PBMAIN = 0
END FUNCTION

Expected exit code: 0

PBXB64.exe xcode-test_xcode_regalloc_address.pb -O2 -o example.exe
.\example.exe
$LASTEXITCODE

Download source

8. Three virtual values in two additions

Step-by-step flow

a, b and c are separate U32 registers explicitly initialized to 0.
X.ADD V(a), V(b), followed by X.ADD V(a), V(c), writes back to a each time.
The stored value is 0; this example illustrates a dependency across several instructions.

#COMPILE EXE
#DIM ALL
GLOBAL reference_result AS LONG
FUNCTION PBMAIN() AS LONG
    #XCODE REGALLOC=AUTO
        X.VREG a:U32
        X.VREG b:U32
        X.VREG c:U32
        X.ZERO V(a)
        X.ZERO V(b)
        X.ZERO V(c)
        X.ADD V(a), V(b)
        X.ADD V(a), V(c)
        X.STORE DWORD PTR [reference_result], V(a)
    #ENDX
    PBMAIN = 0
END FUNCTION

Expected exit code: 0

PBXB64.exe xcode-test_xcode_regalloc_reference.pb -O2 -o example.exe
.\example.exe
$LASTEXITCODE

Download source

9. Merge a result from two X.IF branches

Step-by-step flow

cond and guard are both 0, so equality selects the first branch.
Each branch defines its own intermediate value and moves it into out.
After X.ENDIF, out is defined on the executed path and stored. The example shows why allocation analysis must account for control flow.

#COMPILE EXE
#DIM ALL
GLOBAL liveness_result AS LONG
FUNCTION PBMAIN() AS LONG
    #XCODE REGALLOC=AUTO
        X.VREG cond:U32
        X.VREG guard:U32
        X.VREG left:U32
        X.VREG right:U32
        X.VREG out:U32
        X.ZERO V(cond)
        X.ZERO V(guard)
        X.IF V(cond) == V(guard)
            X.ZERO V(left)
            X.MOVE V(out), V(left)
        X.ELSE
            X.ZERO V(right)
            X.MOVE V(out), V(right)
        X.ENDIF
        X.STORE DWORD PTR [liveness_result], V(out)
    #ENDX
    PBMAIN = 0
END FUNCTION

Expected exit code: 0

PBXB64.exe xcode-test_xcode_regalloc_liveness.pb -O2 -o example.exe
.\example.exe
$LASTEXITCODE

Download source

10. Rematerialize a safe zero value

Step-by-step flow

REGALLOC=AUTO and SPILL=AUTO let the compiler choose fallback strategies.
The AVOID list places heavy register pressure on the virtual zero value.
A value defined by X.ZERO can safely be formed as 0 again. BASIC checks the stored value rather than measuring performance.

' XCODE AUTO rematerializes a safe zero definition instead of spill traffic.
#COMPILE EXE
#DIM ALL
GLOBAL remat_result AS LONG

FUNCTION PBMAIN() AS LONG
    #XCODE REGALLOC=AUTO, SPILL=AUTO
        X.VREG zero:U32
        X.ALLOC AVOID V(zero), r10, r11, r8, r9, rax, rcx, rdx, rdi, rsi, rbx, rbp, r12, r13, r14, r15
        X.ZERO V(zero)
        X.STORE DWORD PTR [remat_result], V(zero)
    #ENDX
    IF remat_result <> 0 THEN
        PBMAIN = 1
        EXIT FUNCTION
    END IF
    PBMAIN = 0
END FUNCTION

Expected exit code: 0

PBXB64.exe xcode-test_xcode_regalloc_remat.pb -O2 -o example.exe
.\example.exe
$LASTEXITCODE

Download source

11. A later redefinition of a register

Step-by-step flow

first and middle are initially set to 0.
The store uses middle while first is redefined later.
This gap matters to liveness analysis. The program illustrates data flow and checks successful completion.

#COMPILE EXE
#DIM ALL
GLOBAL hole_result AS LONG
FUNCTION PBMAIN() AS LONG
    #XCODE REGALLOC=AUTO
        X.VREG first:U32
        X.VREG middle:U32
        X.ZERO V(first)
        X.ZERO V(middle)
        X.STORE DWORD PTR [hole_result], V(middle)
        X.ZERO V(first)
    #ENDX
    PBMAIN = 0
END FUNCTION

Expected exit code: 0

PBXB64.exe xcode-test_xcode_regalloc_holes.pb -O2 -o example.exe
.\example.exe
$LASTEXITCODE

Download source

12. Preserve live values across a RAW block

Step-by-step flow

Seven U32 values receive 1 through 7; X.RAW contains a single nop instruction.
After the barrier, every value is added into a. The compiler must preserve them despite register pressure.
The DWORD store produces 28. Unlike a translation-only check, BASIC explicitly verifies this value.

' XCODE qualification: AUTO spilling preserves a live value across pressure.
#COMPILE EXE
#DIM ALL
GLOBAL spill_result AS LONG

FUNCTION PBMAIN() AS LONG
    #XCODE OPT=2, SPILL=AUTO, FEATURES=BASELINE
        X.VREG a:U32
        X.VREG b:U32
        X.VREG c:U32
        X.VREG d:U32
        X.VREG e:U32
        X.VREG f:U32
        X.VREG g:U32
        X.MOVE V(a), 1
        X.MOVE V(b), 2
        X.MOVE V(c), 3
        X.MOVE V(d), 4
        X.MOVE V(e), 5
        X.MOVE V(f), 6
        X.MOVE V(g), 7
        X.RAW
            nop
        X.ENDRAW
        X.ADD V(a), V(b)
        X.ADD V(a), V(c)
        X.ADD V(a), V(d)
        X.ADD V(a), V(e)
        X.ADD V(a), V(f)
        X.ADD V(a), V(g)
        X.STORE DWORD PTR [spill_result], V(a)
    #ENDX
    IF spill_result <> 28 THEN
        PBMAIN = 1
        EXIT FUNCTION
    END IF
    PBMAIN = 0
END FUNCTION

Expected exit code: 0

PBXB64.exe xcode-test_xcode_spill_auto.pb -O2 -o example.exe
.\example.exe
$LASTEXITCODE

Download source

Larger example: Two loop forms and a nested calculation

Step-by-step flow

X.DO WHILE tests before the body and counts indices 0, 1 and 2. X.DO with X.LOOP UNTIL tests afterward and counts to 2. Separate XCODE blocks store their results in matching 32-bit DWORD variables.
Both X.FOR loops use the excluded end bound 4: outer and inner visit 1, 2 and 3. X.IF uses X.CONTINUE to skip only inner = 2; the outer loop continues.
The total is 1*(1+3) + 2*(1+3) + 3*(1+3) = 24. BASIC checks results 3, 2 and 24 and returns a distinct error code on any mismatch. This is an explained V22 source example; its new native execution remains pending.

' Tutorial: exclusive X.FOR limits and nested control flow.
' DWORD storage matches the U32 virtual registers in this example.
#COMPILE EXE
#DIM ALL
GLOBAL pre_count AS DWORD
GLOBAL post_count AS DWORD
GLOBAL nested_total AS DWORD

FUNCTION PBMAIN() AS LONG
    #XCODE OPT=2, SPILL=AUTO, FEATURES=BASELINE
        X.VREG index:U32
        X.VREG count:U32
        X.MOVE V(index), 0
        X.MOVE V(count), 0
        X.DO WHILE V(index) < 3
            X.INC V(count)
            X.INC V(index)
        X.LOOP
        X.STORE DWORD PTR [pre_count], V(count)
    #ENDX

    #XCODE OPT=2, SPILL=AUTO, FEATURES=BASELINE
        X.VREG count:U32
        X.MOVE V(count), 0
        X.DO
            X.INC V(count)
        X.LOOP UNTIL V(count) == 2
        X.STORE DWORD PTR [post_count], V(count)
    #ENDX

    #XCODE OPT=2, SPILL=AUTO, FEATURES=BASELINE
        X.VREG outer:U32
        X.VREG inner:U32
        X.VREG product:U32
        X.VREG total:U32
        X.MOVE V(total), 0
        X.FOR V(outer), 1, 4, 1
            X.FOR V(inner), 1, 4, 1
                X.IF V(inner) == 2
                    X.CONTINUE
                X.ENDIF
                X.MOVE V(product), V(outer)
                X.MUL V(product), V(inner)
                X.ADD V(total), V(product)
            X.NEXT V(inner)
        X.NEXT V(outer)
        X.STORE DWORD PTR [nested_total], V(total)
    #ENDX

    IF pre_count <> 3 THEN PBMAIN = 1 : EXIT FUNCTION
    IF post_count <> 2 THEN PBMAIN = 2 : EXIT FUNCTION
    IF nested_total <> 24 THEN PBMAIN = 3 : EXIT FUNCTION
    PBMAIN = 0
END FUNCTION

Expected exit code: 0

PBXB64.exe xcode-xcode-workshop-loops.pb -O2 -o example.exe
.\example.exe
$LASTEXITCODE

Download source

All sources for this tutorial

Each example has its own folder; the README lists compiler commands. Included support files retain matching paths.

Download all 13 examples as ZIP

Bridging

X.STORE connects an XCODE block with a BASIC storage slot. QWORD covers a complete 64-bit LONG; DWORD handles 32 bits only. The full command reference is on the XCODE feature page.

Explore complete source pairs All XCODE commands