1041 lines
20 KiB
Plaintext
1041 lines
20 KiB
Plaintext
// 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*
|