// Moved from docs/src/build-and-tooling/BUILD_OPTIONS.adoc to docs/working/scratch/src/build-and-tooling/BUILD_OPTIONS.adoc on 2026-06-16 (docs reorg Phase 2)
== StarForth Build Options Reference
:toc: left
:toc-title: Contents
:toclevels: 3
xref:../README.adoc[← Back to Documentation Index]



*Comprehensive guide to all build-time configuration options and
preprocessor defines*

'''''

=== Overview

StarForth supports numerous build-time configuration options that
control optimizations, features, platform support, and debugging
capabilities. This document catalogs all available options with
descriptions, valid values, and usage examples.

'''''

=== Table of Contents

[arabic]
. link:#performance-optimization-options[Performance Optimization
Options]
. link:#architecture-options[Architecture Options]
. link:#platformtarget-options[Platform/Target Options]
. link:#debugging-and-profiling-options[Debugging and Profiling Options]
. link:#block-system-options[Block System Options]
. link:#memory-configuration-options[Memory Configuration Options]
. link:#feature-flags[Feature Flags]
. link:#build-system-variables[Build System Variables]

'''''

=== Performance Optimization Options

==== `+USE_ASM_OPT+`

*Enable hand-optimized assembly implementations for critical operations*

* *Type:* Integer (0 or 1)
* *Default:* 0 (disabled)
* *Affects:* Stack operations, arithmetic, string operations, min/max,
bit operations

*Description:*

Enables architecture-specific assembly optimizations for:

* `+vm_push+` / `+vm_pop+` - Data stack operations
* `+vm_rpush+` / `+vm_rpop+` - Return stack operations
* `+vm_add_check_overflow+` / `+vm_sub_check_overflow+` - Arithmetic
with overflow detection
* `+vm_mul+` / `+vm_div+` - Multiply/divide optimizations
* `+vm_strcmp_asm+` / `+vm_memcpy_asm+` - String/memory operations
* `+vm_min_asm+` / `+vm_max_asm+` - Conditional move optimizations
* `+vm_abs_asm+` - Absolute value (ARM64)
* `+vm_clz+` / `+vm_ctz+` - Count leading/trailing zeros (ARM64)
* `+vm_prefetch+` / `+vm_prefetch_stream+` - Cache prefetching (ARM64)

*Performance impact:* ~20-25% speedup on x86_64, ~15-20% on ARM64

*Enabled by:*

[source,bash]
----
make fastest    # USE_ASM_OPT=1
make fast       # USE_ASM_OPT=1
make turbo      # USE_ASM_OPT=1
make pgo        # USE_ASM_OPT=1
----

*Manual usage:*

[source,bash]
----
make CFLAGS="$(BASE_CFLAGS) -DUSE_ASM_OPT=1 -O3"
----

*See also:* ASM_OPTIMIZATIONS.md

'''''

==== `+USE_DIRECT_THREADING+`

*Enable direct-threaded inner interpreter with computed goto*

* *Type:* Integer (0 or 1)
* *Default:* 0 (disabled, uses indirect threading)
* *Affects:* Inner interpreter dispatch mechanism

*Description:*

Switches from *indirect threading* (traditional Forth) to *direct
threading* using GCC’s computed goto extension ( `+&&label+` and
`+goto *ptr+`). In direct threading, each word’s code address points
directly to native code instead of through an indirection table.

*Benefits:*

* Eliminates one level of indirection in the inner interpreter
* Better branch prediction and instruction cache utilization
* Typically 30-40% faster than indirect threading

*Requirements:*

* GCC or Clang (uses `+__label__+` and computed goto)
* Must be combined with `+USE_ASM_OPT=1+`

*Performance impact:* ~30-40% speedup when combined with ASM
optimizations

*Enabled by:*

[source,bash]
----
make fastest    # USE_DIRECT_THREADING=1
make fast       # USE_DIRECT_THREADING=1
make pgo        # USE_DIRECT_THREADING=1
----

*Manual usage:*

[source,bash]
----
make CFLAGS="$(BASE_CFLAGS) -DUSE_ASM_OPT=1 -DUSE_DIRECT_THREADING=1 -O3"
----

*Architectural support:*

* *x86_64:* Full support (see `+vm_inner_interp_asm.h+`)
* *ARM64:* Full support (see `+vm_inner_interp_arm64.h+`)

'''''

==== `+NDEBUG+`

*Disable assertions and enable aggressive optimizations*

* *Type:* Preprocessor flag (defined or not)
* *Default:* Undefined (assertions enabled)
* *Affects:* `+assert()+` macros, debug logging in hot paths

*Description:*

Standard C macro that disables `+assert()+` checks. When defined, all
assertion overhead is removed from the binary. Also used by StarForth to
conditionally disable debug logging in performance-critical sections.

*Performance impact:* ~5-10% speedup (removes assertion checks)

*Enabled by:*

[source,bash]
----
make fastest    # -DNDEBUG
make fast       # -DNDEBUG
make turbo      # -DNDEBUG
make pgo        # -DNDEBUG
----

*Manual usage:*

[source,bash]
----
make CFLAGS="$(BASE_CFLAGS) -DNDEBUG -O3"
----

'''''

==== `+STARFORTH_PERFORMANCE+`

*Enable aggressive performance optimizations with reduced safety checks*

* *Type:* Preprocessor flag
* *Default:* Undefined
* *Affects:* Stack bounds checking, overflow detection

*Description:*

Experimental flag that trades safety for speed. When enabled:

* Reduces stack bounds checking in hot paths (DUP, SWAP, etc.)
* Uses `+UNLIKELY()+` hints to optimize for common case
* Assumes well-behaved Forth code

*⚠️ Warning:* Only use for production code that has been thoroughly
tested. Stack overflows may go undetected.

*Performance impact:* ~5-8% additional speedup over standard
optimizations

*Manual usage:*

[source,bash]
----
make CFLAGS="$(BASE_CFLAGS) -DSTARFORTH_PERFORMANCE -DNDEBUG -O3"
----

*Code references:*

* `+src/word_source/stack_words.c:58+` - DUP optimization
* `+src/word_source/stack_words.c:117+` - SWAP optimization

'''''

=== Architecture Options

==== `+ARCH_X86_64+`

*Target x86-64 architecture (AMD64, Intel 64)*

* *Type:* Integer (0 or 1)
* *Default:* Auto-detected from compiler macros
* *Set by:* `+arch_detect.h+` automatically

*Auto-detection:*

[source,c]
----
#if defined(__x86_64__) || defined(_M_X64) || defined(__amd64__)
#define ARCH_X86_64 1
----

*Enables:*

* x86_64 assembly optimizations (`+vm_asm_opt.h+`)
* SSE4.2 string instructions (if supported)
* x86_64 direct threading (`+vm_inner_interp_asm.h+`)

*Makefile support:*

[source,bash]
----
# Auto-detected
make fastest

# Manual override
make ARCH_DEFINES="-DARCH_X86_64=1" ARCH_FLAGS="-march=native"
----

'''''

==== `+ARCH_ARM64+`

*Target ARM64 architecture (AArch64, ARMv8-A)*

* *Type:* Integer (0 or 1)
* *Default:* Auto-detected from compiler macros
* *Set by:* `+arch_detect.h+` automatically

*Auto-detection:*

[source,c]
----
#if defined(__aarch64__) || defined(_M_ARM64) || defined(__arm64__)
#define ARCH_ARM64 1
----

*Enables:*

* ARM64 assembly optimizations (`+vm_asm_opt_arm64.h+`)
* NEON SIMD instructions (if supported)
* ARM64 direct threading (`+vm_inner_interp_arm64.h+`)
* ARM-specific instructions: CLZ, CTZ, RBIT, REV, etc.

*Makefile support:*

[source,bash]
----
# Native ARM64 build
make rpi4

# Cross-compile from x86_64
make rpi4-cross
----

'''''

==== `+ARCH_NAME+`

*Human-readable architecture string*

* *Type:* String literal
* *Values:* `+"x86_64"+`, `+"ARM64"+`, `+"Unknown"+`
* *Default:* Auto-set based on detected architecture

*Usage:*

[source,bash]
----
make help  # Shows "CURRENT PLATFORM: x86_64"
----

'''''

=== Platform/Target Options

==== `+STARFORTH_MINIMAL+`

*Build minimal/embedded version without standard library dependencies*

* *Type:* Preprocessor flag
* *Default:* Undefined (full-featured build)
* *Affects:* I/O, logging, memory allocation

*Description:*

Enables minimal build mode for embedded systems or bare-metal
environments. When defined:

* Disables ANSI color codes in logging
* Uses minimal I/O (no fprintf colors)
* Prepares for custom memory allocators
* Suitable for microkernel environments (L4Re)

*Compiler flags added:*

[source,bash]
----
-DSTARFORTH_MINIMAL=1 -nostdlib -ffreestanding
----

*Linker flags:*

[source,bash]
----
-nostdlib
----

*Enabled by:*

[source,bash]
----
make minimal
make l4re
----

*Code references:*

* `+src/log.c:36-46+` - Minimal logging (no colors)
* `+src/log.c:110-118+` - Simplified log output

'''''

==== `+L4RE_TARGET+`

*Build for L4Re microkernel environment*

* *Type:* Preprocessor flag
* *Default:* Undefined
* *Affects:* Block I/O backend selection, ROMFS usage

*Description:*

Targets the L4Re microkernel operating system. Enables:

* L4Re-specific block storage backend (when implemented)
* ROMFS file access instead of POSIX filesystem
* Minimal build mode (implies `+STARFORTH_MINIMAL=1+`)

*Status:* Partially implemented (ROMFS TODO)

*Enabled by:*

[source,bash]
----
make l4re
----

*Code references:*

* `+src/word_source/starforth_words.c:225+` - L4Re ROMFS check (TODO)
* `+include/blkio_factory.h+` - Backend selection

*See also:* L4RE_INTEGRATION.md

'''''

=== Debugging and Profiling Options

==== `+DEBUG+`

*Enable debug build with symbols and verbose logging*

* *Type:* Preprocessor flag
* *Default:* Undefined
* *Affects:* Optimization level, debugging symbols

*Description:*

Debug builds include:

* Full debugging symbols (`+-g+`)
* No optimization (`+-O0+`)
* All assertions enabled
* Verbose logging throughout

*Enabled by:*

[source,bash]
----
make debug
----

*Compiler flags:*

[source,bash]
----
-O0 -g -DDEBUG
----

'''''

==== `+PROFILE_ENABLED+`

*Enable built-in profiler for performance analysis*

* *Type:* Integer (0 or 1)
* *Default:* 0 (disabled)
* *Affects:* Profiler instrumentation

*Description:*

Enables StarForth’s built-in profiler which tracks:

* Per-word execution counts
* Call graph (caller/callee relationships)
* Stack operation counts
* Total instruction counts

*Performance overhead:* ~10-15% when enabled

*Enabled by:*

[source,bash]
----
make profile
----

*Runtime usage:*

[source,bash]
----
./build/starforth --profile 2      # Enable with depth 2
./build/starforth --profile-report # Show profiling results
----

*See also:* `+include/profiler.h+`

'''''

==== `+STRICT_PTR+`

*Enable strict pointer mode (VM_STRICT_PTR)*

* *Type:* Integer (0 or 1)
* *Default:* 1 (enabled)
* *Affects:* Forth address ↔ pointer conversions

*Description:*

Controls how Forth addresses (cell_t) map to C pointers:

* *STRICT_PTR=1 (default):* Forth addresses ARE real pointers (cell_t =
uintptr_t)
* *STRICT_PTR=0:* Forth addresses are indices/offsets (for segmented
memory models)

*Usage:*

[source,bash]
----
# Default (strict pointers)
make

# Disable strict pointers
make STRICT_PTR=0
----

*Code references:*

* `+src/vm_api.c:202+` - `+vm_addr_from_ptr+` implementation
* `+Makefile:37+` - `+BASE_CFLAGS+` includes
`+-DSTRICT_PTR=$(STRICT_PTR)+`

'''''

=== Block System Options

==== `+BLKCFG_DEFAULT_FBS+`

*Default Forth Block Size*

* *Type:* Integer (bytes)
* *Default:* 1024
* *Affects:* Block I/O buffer sizes

*Description:*

Sets the default block size for Forth block storage. Standard Forth uses
1024-byte blocks.

*Valid values:* Typically 1024, 2048, or 4096

*Code references:*

* `+include/blkcfg.h+` - Block configuration constants

'''''

==== `+BLKCFG_PATH_MAX+`

*Maximum path length for block storage files*

* *Type:* Integer (bytes)
* *Default:* 4096
* *Affects:* Path buffer allocation

'''''

==== `+BLK_FORTH_SYS_RESERVED+`

*Number of system-reserved Forth blocks*

* *Type:* Integer (block count)
* *Default:* 32 (blocks 0-31)
* *Affects:* LBN→PBN mapping

*Description:*

Reserves the first N blocks in RAM for system use (INIT blocks,
bootstrap code, etc.). These blocks are hidden from normal user access.

'''''

==== `+BLK_DISK_SYS_RESERVED+`

*Number of system-reserved disk blocks*

* *Type:* Integer (block count)
* *Default:* 32 (PBN 1024-1055)
* *Affects:* Persistent block storage mapping

'''''

=== Memory Configuration Options

==== `+DATA_STACK_SIZE+`

*Size of data stack*

* *Type:* Integer (cells)
* *Default:* 256
* *Affects:* Data stack allocation

*Code references:*

* `+include/vm.h+` - VM structure definition

'''''

==== `+RETURN_STACK_SIZE+`

*Size of return stack*

* *Type:* Integer (cells)
* *Default:* 256
* *Affects:* Return stack allocation

'''''

==== `+STARFORTH_STATE_BYTES+`

*Total state buffer size for minimal builds*

* *Type:* Integer (bytes)
* *Default:* 8192
* *Affects:* State buffer allocation in main.c

*Code references:*

* `+src/main.c:40-42+` - State buffer definition

'''''

==== `+SF_FC_BUCKETS+`

*Number of forget-chain hash buckets*

* *Type:* Integer (count)
* *Default:* Defined in vm.h
* *Affects:* Dictionary management performance

'''''

=== Feature Flags

==== `+STARFORTH_ANSI+`

*Enable ANSI escape codes for terminal control*

* *Type:* Preprocessor flag
* *Default:* Undefined
* *Affects:* LIST and EDIT word rendering

*Description:*

When defined, enables ANSI terminal control sequences for:

* Screen clearing (`+\x1b[2J+`)
* Cursor positioning (`+\x1b[H+`)
* Colored line numbers in EDIT

*Code references:*

* `+src/word_source/editor_words.c:74+` - Line rendering
* `+src/word_source/editor_words.c:188+` - Screen clear
* `+src/word_source/editor_words.c:202+` - Colored line numbers

*Manual usage:*

[source,bash]
----
make CFLAGS="$(BASE_CFLAGS) -DSTARFORTH_ANSI -O2"
----

'''''

==== `+VM_HAS_CURRENT_ENTRY+`

*Enable current dictionary entry tracking*

* *Type:* Preprocessor flag
* *Default:* Defined (feature enabled)
* *Affects:* Dictionary management, SEE word

*Description:*

Enables `+vm->current_entry+` field which tracks the currently-compiling
word. Required for:

* SEE decompiler
* Recursive word definitions
* Dictionary introspection

*Code references:*

* `+include/vm.h+` - VM structure
* `+src/word_source/dictionary_words.c+` - SEE implementation

'''''

=== Build System Variables

==== `+CC+`

*C compiler*

* *Type:* String
* *Default:* `+gcc+`
* *Valid values:* `+gcc+`, `+clang+`, `+aarch64-linux-gnu-gcc+`

*Usage:*

[source,bash]
----
make CC=clang
make CC=aarch64-linux-gnu-gcc  # Cross-compile for ARM64
----

'''''

==== `+CFLAGS+`

*Compiler flags*

* *Type:* String
* *Default:* See Makefile BASE_CFLAGS + optimizations

*Usage:*

[source,bash]
----
make CFLAGS="-O3 -march=native -DUSE_ASM_OPT=1"
----

'''''

==== `+LDFLAGS+`

*Linker flags*

* *Type:* String
* *Default:*
`+-Wl,--gc-sections -s -flto=auto -fuse-linker-plugin -static+`

*Usage:*

[source,bash]
----
make LDFLAGS="-static -s"
----

'''''

==== `+MINIMAL+`

*Enable minimal build*

* *Type:* Integer (0 or 1)
* *Default:* 0

*Usage:*

[source,bash]
----
make MINIMAL=1
----

*Effect:* Sets `+STARFORTH_MINIMAL=1+`, adds
`+-nostdlib -ffreestanding+`

'''''

==== `+ASM+`

*Generate assembly output*

* *Type:* Integer (0 or 1)
* *Default:* 0

*Usage:*

[source,bash]
----
make ASM=1
----

*Effect:* Generates `+.s+` assembly files alongside `+.o+` object files
in `+build/+`

'''''

=== Configuration Matrix

==== Common Build Configurations

[width="100%",cols="14%,13%,22%,8%,19%,24%",options="header",]
|===
|Target |USE_ASM_OPT |USE_DIRECT_THREADING |NDEBUG |Optimization |Use
Case
|`+debug+` |0 |0 |No |-O0 -g |Development, debugging

|`+all+` |1 |0 |No |-O2 |Default build

|`+turbo+` |1 |0 |Yes |-O3 -flto |Fast without threading

|`+fast+` |1 |1 |Yes |-O3 |Fast, readable asm

|`+fastest+` |1 |1 |Yes |-O3 -flto |Maximum performance

|`+pgo+` |1 |1 |Yes |-O3 -fprofile-use |Absolute fastest

|`+minimal+` |0 |0 |No |-O2 |Embedded/bare-metal

|`+l4re+` |0 |0 |No |-O2 |L4Re microkernel

|`+profile+` |0 |0 |No |-O1 -g |Profiling enabled
|===

'''''

=== Architecture Detection

StarForth automatically detects the target architecture at compile time.
The following macros are checked (in order):

==== x86_64 Detection

[source,c]
----
#if defined(__x86_64__) || defined(_M_X64) || defined(__amd64__)
  ARCH_X86_64 = 1
----

*Compilers:* GCC, Clang, MSVC

'''''

==== ARM64 Detection

[source,c]
----
#if defined(__aarch64__) || defined(_M_ARM64) || defined(__arm64__)
  ARCH_ARM64 = 1
----

*Compilers:* GCC, Clang (aarch64-linux-gnu-gcc), Apple Clang

'''''

==== Unknown Architecture

[source,c]
----
#else
  #warning "Unknown architecture, assembly optimizations disabled"
----

Falls back to pure C implementations.

'''''

=== Optimization Level Guidelines

==== Development (`+-O0 -g+`)

* *Fastest compile time*
* *Slowest runtime* (10x slower than optimized)
* Full debugging symbols
* All assertions enabled
* Best for: Initial development, debugging crashes

==== Balanced (`+-O2+`)

* *Good compile time* (~2-3x slower than -O0)
* *Decent runtime* (3-4x faster than -O0)
* Some inlining, loop optimizations
* Best for: Default builds, testing

==== High Performance (`+-O3+`)

* *Slower compile time* (~5x slower than -O0)
* *Fast runtime* (5-6x faster than -O0)
* Aggressive inlining, vectorization
* Best for: Production builds

==== Maximum Performance (`+-O3 -flto -march=native -fprofile-use+`)

* *Slowest compile time* (10x+ slower than -O0, multi-stage)
* *Fastest runtime* (7-8x faster than -O0)
* Link-time optimization, CPU-specific instructions, profile-guided
optimization
* Best for: Release builds, benchmarking

'''''

=== Usage Examples

==== Example 1: Maximum Performance Native Build

[source,bash]
----
make clean
make pgo
----

*Result:* PGO-optimized binary with ASM + direct threading + LTO

'''''

==== Example 2: Debug Build with Profiler

[source,bash]
----
make clean
make profile
./build/starforth --profile 3 --profile-report
----

*Result:* Instrumented binary with profiling enabled, depth 3 call graph

'''''

==== Example 3: Cross-Compile for Raspberry Pi 4

[source,bash]
----
make rpi4-cross
scp build/starforth pi@raspberrypi.local:~/
----

*Result:* Static ARM64 binary optimized for Cortex-A72

'''''

==== Example 4: Minimal Build for Embedded System

[source,bash]
----
make minimal
----

*Result:* Bare-metal binary with no libc dependencies

'''''

==== Example 5: Custom Optimization Build

[source,bash]
----
make clean
make CFLAGS="$(BASE_CFLAGS) -O3 -march=znver3 -DUSE_ASM_OPT=1 -DUSE_DIRECT_THREADING=1 -DNDEBUG" \
     LDFLAGS="-flto -s"
----

*Result:* AMD Zen 3 optimized build with all features

'''''

==== Example 6: Generate Assembly Listings

[source,bash]
----
make asm
less build/stack_management.s
----

*Result:* Assembly output for all source files in `+build/*.s+`

'''''

=== Compiler-Specific Notes

==== GCC (Recommended)

* *Minimum version:* GCC 7.0+
* *Best version:* GCC 11.0+ (improved PGO, better ARM64 codegen)
* Full support for all optimizations

==== Clang

* *Minimum version:* Clang 10.0+
* Full support for ASM optimizations
* Computed goto supported (direct threading works)
* May produce slightly different code than GCC

==== Cross-Compilation

*ARM64 from x86_64:*

[source,bash]
----
sudo apt-get install gcc-aarch64-linux-gnu
make CC=aarch64-linux-gnu-gcc rpi4-cross
----

*Requirements:*

* Cross-compiler toolchain
* Static linking recommended (`+-static+`)

'''''

=== Troubleshooting

==== Issue: "`Unknown architecture`" warning

*Cause:* Compiling on unsupported platform (32-bit, RISC-V, etc.)

*Solution:*

[arabic]
. Assembly optimizations disabled automatically
. Falls back to pure C implementations
. To add support, modify `+arch_detect.h+`

'''''

==== Issue: Direct threading not working

*Symptoms:* Build succeeds but no performance gain

*Check:*

[arabic]
. Ensure `+USE_DIRECT_THREADING=1+` is set
. Verify `+USE_ASM_OPT=1+` is also set (required)
. Check architecture is x86_64 or ARM64
. GCC/Clang compiler (not MSVC)

*Verify at runtime:*

[source,forth]
----
ok> WORDS-INFO
( Look for "Direct threading: ENABLED" )
----

'''''

==== Issue: PGO warnings about coverage mismatch

*Cause:* Source changed between instrumentation and optimization builds

*Solution:*

[source,bash]
----
make clean
make pgo  # Runs full clean rebuild automatically
----

'''''

=== Performance Tuning Checklist

For absolute maximum performance:

* ✅ Use `+make pgo+` (profile-guided optimization)
* ✅ Enable `+USE_ASM_OPT=1+` (assembly optimizations)
* ✅ Enable `+USE_DIRECT_THREADING=1+` (direct threading)
* ✅ Define `+NDEBUG+` (disable assertions)
* ✅ Use `+-O3 -flto -march=native+` (aggressive optimization)
* ✅ Use `+-fno-plt -fno-semantic-interposition+` (reduce indirection)
* ✅ Use `+-funroll-loops -finline-functions+` (code expansion)
* ✅ Static linking (`+-static+`) to eliminate PLT overhead
* ✅ Strip symbols (`+-s+`) to reduce binary size

*Result:* ~7-8x faster than debug build, ~1.2-1.5x faster than standard
`+-O3+`

'''''

=== See Also

* PGO_GUIDE.md - Profile-guided optimization guide
* ASM_OPTIMIZATIONS.md - Assembly optimization details
* ARCHITECTURE.md - System architecture overview
* RASPBERRY_PI_BUILD.md - ARM64 build guide
* L4RE_INTEGRATION.md - Microkernel integration

'''''

*End of Build Options Reference*
