CompilerX32 Documentation

Help files, command reference, preprocessor guide, and multi-language syntax documentation.

CompilerX32 Help (CHM)

Complete compiled HTML help file with command reference for all 635 keywords, multi-language syntax guide, preprocessor documentation, and built-in macro reference.

Preprocessor Docs Updated

Preprocessor Documentation (Updated)

Multi-Pass Architecture

The CompilerX32 preprocessor runs in three phases before the lexer:

PASS 1 (COLLECT): Gather all macros, equates, includes PASS 2 (EXPAND): Expand macros, equates, builtins (repeat until stable) PASS 3 (CONDITIONALS): Strip #if/#ifdef blocks

This eliminates macro phase errors — a macro can reference another macro defined later in the source. The stability loop (Pass 2) repeats until no further changes occur, handling macros that define macros and macros that contain #INCLUDE directives.

MACRO / END MACRO DONE

Parameterized macros with \1..\16 substitution, MACROTEMP for unique labels, MACRO FUNCTION return expressions. Recursive protection and nested expansion up to 128 iterations per line.

Multi-Language Guide DONE

Using BASIC, C, ASM, and PILOT in the same source file with the language-switching stack. Nest up to 32,768 levels. C headers via #CINCLUDE with automatic #CCODE/#ENDC wrapping.

Built-in Macros DONE

Eight built-in macros: __LINE__, __FILE__, __DATE__, __TIME__, __COUNTER__ (monotonic counter), __CX32__, __CX32_VERSION__, __PBWIN__.

C-Preprocessor Features DONE

Inside #CCODE blocks: ## token pasting, # stringification, #undef, #error, #pragma, #warning, #line.

#INCLUDE System DONE

Recursive include with circular detection. #INCLUDE, #INCLUDE ONCE, #CINCLUDE, #AINCLUDE, #BINCLUDE. Multi-pass: new includes revealed by macro expansion trigger pipeline restart.

Language Reference IN PROGRESS

Complete PowerBASIC-compatible syntax reference with all 635 keywords, 1,564 constants, and 27 data types. Being updated as lexer/parser coverage expands.

CLI Reference DONE

Command-line options: /L (log), /Q (quiet), /I (include paths), /O (output filename). Build scripts: Build_Pipeline.ps1, scripts/test_compile.ps1.

Self-Hosting Guide TODO

Gen1/Gen2/Gen3 self-hosting verification procedures, expected outputs, and troubleshooting. Will be available once self-hosting chain is stable.

Macro Expansion Example

' Define parameterized macro MACRO ADD(x, y) = (\1 + \2) ' Define macro with MACROTEMP MACRO SWAP(a, b) MACROTEMP tmp tmp = \1 \1 = \2 \2 = tmp END MACRO ' Use them DIM x AS LONG, y AS LONG x = 10: y = 20 SWAP(x, y) ' tmp -> tmp_MT0001 (unique per expansion) DIM r AS LONG r = ADD(3, 4) ' r = (3 + 4) = 7 ' Built-in macros PRINT __LINE__ ' Current line number PRINT __COUNTER__ ' 0 (increments each use) PRINT __FILE__ ' "source.bas"

Alpha Documentation

Documentation is being updated as features are implemented. The CHM help file and online reference will be available with the first public alpha release.

Back to CompilerX32