%% SCRAP: architecture/build-and-tooling/BUILD_OPTIONS
%% SOURCE: docs/working/architecture/build-and-tooling/BUILD_OPTIONS.adoc
%% STATUS: CURRENT
%% FITS: dev-guide/ch-build, user-guide/app-flags, cookbook/app-flags
%% EDITORIAL: lifted — prose rewritten to press voice

\section{Build Options Reference}
\label{sec:build-options}

StarForth exposes a comprehensive set of build-time configuration options
controlling optimizations, feature selection, platform targeting, and
debugging. All options are passed as preprocessor defines via \texttt{CFLAGS}
or as Makefile variables. Architecture detection runs automatically at compile
time through \texttt{arch\_detect.h}.

% ----------------------------------------------------------------
\subsection{Performance Optimization Options}
\label{sec:build-perf}

\subsubsection{\texttt{USE\_ASM\_OPT}}

Enables hand-optimized, architecture-specific assembly implementations for
performance-critical operations. Type: integer (0 or 1). Default: 0.

Affected routines include:

\begin{itemize}
  \item \texttt{vm\_push} / \texttt{vm\_pop} — data stack operations
  \item \texttt{vm\_rpush} / \texttt{vm\_rpop} — return stack operations
  \item \texttt{vm\_add\_check\_overflow} / \texttt{vm\_sub\_check\_overflow} — arithmetic with overflow detection
  \item \texttt{vm\_mul} / \texttt{vm\_div} — multiply and divide
  \item \texttt{vm\_strcmp\_asm} / \texttt{vm\_memcpy\_asm} — string and memory operations
  \item \texttt{vm\_min\_asm} / \texttt{vm\_max\_asm} — conditional-move optimizations
  \item \texttt{vm\_abs\_asm} — absolute value (ARM64)
  \item \texttt{vm\_clz} / \texttt{vm\_ctz} — count leading/trailing zeros (ARM64)
  \item \texttt{vm\_prefetch} / \texttt{vm\_prefetch\_stream} — cache prefetching (ARM64)
\end{itemize}

Typical performance impact: \(\approx\)20--25\% on x86\_64; \(\approx\)15--20\% on ARM64.
Enabled automatically by the \texttt{fastest}, \texttt{fast}, \texttt{turbo}, and \texttt{pgo} targets.

% ----------------------------------------------------------------
\subsubsection{\texttt{USE\_DIRECT\_THREADING}}

Switches the inner interpreter from indirect threading (the FORTH-79 default)
to direct threading using GCC computed-goto (\texttt{\&\&label} / \texttt{goto *ptr}).
In direct-threaded mode each word's code field points directly to native code,
eliminating one indirection level per dispatch. Type: integer (0 or 1).
Default: 0.

Requirements: GCC or Clang; must be combined with \texttt{USE\_ASM\_OPT=1}.
Full support is provided for x86\_64 (\texttt{vm\_inner\_interp\_asm.h}) and
ARM64 (\texttt{vm\_inner\_interp\_arm64.h}).

Typical performance impact: \(\approx\)30--40\% over indirect threading when
combined with \texttt{USE\_ASM\_OPT=1}. Enabled by \texttt{fastest}, \texttt{fast},
and \texttt{pgo} targets.

% ----------------------------------------------------------------
\subsubsection{\texttt{NDEBUG}}

Standard C99 macro. When defined, all \texttt{assert()} calls compile to
nothing, and StarForth additionally suppresses debug logging in hot paths.
Default: undefined (assertions active). Typical impact: \(\approx\)5--10\% speedup.

% ----------------------------------------------------------------
\subsubsection{\texttt{STARFORTH\_PERFORMANCE}}

Experimental flag that trades safety for throughput. Reduces stack-bounds
checking in hot paths (DUP, SWAP, etc.) and applies \texttt{UNLIKELY()} branch
hints, assuming well-formed Forth input.

\textbf{Caution:} stack overflows may go undetected. Use only on code that has
been exhaustively tested. Typical additional gain: \(\approx\)5--8\% over
standard \texttt{-O3}. Relevant sources: \texttt{src/word\_source/stack\_words.c:58}
(DUP), \texttt{src/word\_source/stack\_words.c:117} (SWAP).

% ----------------------------------------------------------------
\subsection{Architecture Options}
\label{sec:build-arch}

Architecture detection is automatic via \texttt{arch\_detect.h}; manual
overrides are available for cross-compilation scenarios.

\subsubsection{\texttt{ARCH\_X86\_64}}

Targets x86-64 (AMD64 / Intel 64). Auto-detected from compiler predefined
macros (\texttt{\_\_x86\_64\_\_}, \texttt{\_M\_X64}, \texttt{\_\_amd64\_\_}).
Enables x86\_64 assembly optimizations, SSE4.2 string instructions, and the
x86\_64 direct-threading header.

\subsubsection{\texttt{ARCH\_ARM64}}

Targets AArch64 (ARMv8-A). Auto-detected from \texttt{\_\_aarch64\_\_},
\texttt{\_M\_ARM64}, and \texttt{\_\_arm64\_\_}. Enables NEON SIMD instructions,
ARM64-specific instructions (CLZ, CTZ, RBIT, REV), ARM64 assembly
optimizations, and ARM64 direct threading.

Native ARM64 build: \texttt{make rpi4}. Cross-compile from x86\_64:
\texttt{make rpi4-cross}.

\subsubsection{\texttt{ARCH\_NAME}}

Human-readable string set automatically: \texttt{"x86\_64"}, \texttt{"ARM64"},
or \texttt{"Unknown"}. Displayed by \texttt{make help}.

On an unrecognized architecture the build emits a compiler warning and falls
back to pure-C implementations; no assembly optimizations are loaded.

% ----------------------------------------------------------------
\subsection{Platform / Target Options}
\label{sec:build-platform}

\subsubsection{\texttt{STARFORTH\_MINIMAL}}

Enables minimal/freestanding build suitable for bare-metal or microkernel
environments. When defined: ANSI color codes are suppressed in logging; I/O
is reduced to minimal output; the build links with \texttt{-nostdlib
-ffreestanding}. Enabled by \texttt{make minimal} and \texttt{make l4re}.

\subsubsection{\texttt{L4RE\_TARGET}}

Targets the L4Re microkernel operating system. Enables the L4Re block-storage
backend, ROMFS file access in place of POSIX, and implies
\texttt{STARFORTH\_MINIMAL=1}. Status: partially implemented (ROMFS stub
present). See \texttt{src/word\_source/starforth\_words.c:225} and
\texttt{include/blkio\_factory.h}.

% ----------------------------------------------------------------
\subsection{Debugging and Profiling Options}
\label{sec:build-debug}

\subsubsection{\texttt{DEBUG}}

Debug builds compile with \texttt{-O0 -g -DDEBUG}: no optimization, full
debugging symbols, all assertions enabled, verbose logging throughout. Enabled
by \texttt{make debug}.

\subsubsection{\texttt{PROFILE\_ENABLED}}

Activates StarForth's built-in profiler. Type: integer (0 or 1). Default: 0.
The profiler tracks per-word execution counts, call-graph relationships
(caller/callee), stack operation counts, and total instruction counts.
Overhead: \(\approx\)10--15\%.

\begin{lstlisting}[language=bash]
./build/starforth --profile 2      # enable at depth 2
./build/starforth --profile-report # print results
\end{lstlisting}

See \texttt{include/profiler.h}.

\subsubsection{\texttt{STRICT\_PTR}}

Controls the Forth address--to--C pointer mapping. Type: integer (0 or 1).
Default: 1.

\begin{itemize}
  \item \texttt{STRICT\_PTR=1} — Forth addresses are real pointers (\texttt{cell\_t = uintptr\_t}).
  \item \texttt{STRICT\_PTR=0} — Forth addresses are indices/offsets (segmented memory models).
\end{itemize}

Disable only for benchmarking or non-hosted targets. See
\texttt{src/vm\_api.c:202} and \texttt{Makefile:37}.

% ----------------------------------------------------------------
\subsection{Block System Options}
\label{sec:build-block}

\begin{itemize}
  \item \texttt{BLKCFG\_DEFAULT\_FBS} — default Forth block size in bytes (default: 1024). See \texttt{include/blkcfg.h}.
  \item \texttt{BLKCFG\_PATH\_MAX} — maximum path length for block-storage files (default: 4096).
  \item \texttt{BLK\_FORTH\_SYS\_RESERVED} — number of system-reserved RAM blocks, hidden from user access (default: 32, blocks 0--31).
  \item \texttt{BLK\_DISK\_SYS\_RESERVED} — number of system-reserved disk blocks (default: 32, PBN 1024--1055).
\end{itemize}

% ----------------------------------------------------------------
\subsection{Memory Configuration Options}
\label{sec:build-memory}

\begin{itemize}
  \item \texttt{DATA\_STACK\_SIZE} — data stack depth in cells (default: 256). See \texttt{include/vm.h}.
  \item \texttt{RETURN\_STACK\_SIZE} — return stack depth in cells (default: 256).
  \item \texttt{STARFORTH\_STATE\_BYTES} — total state-buffer size for minimal builds (default: 8192). See \texttt{src/main.c:40--42}.
  \item \texttt{SF\_FC\_BUCKETS} — number of forget-chain hash buckets; defined in \texttt{vm.h}.
\end{itemize}

% ----------------------------------------------------------------
\subsection{Feature Flags}
\label{sec:build-features}

\subsubsection{\texttt{STARFORTH\_ANSI}}

Enables ANSI escape sequences for terminal control in the block editor
(LIST, EDIT): screen clear (\texttt{\textbackslash x1b[2J}), cursor
positioning, and colored line numbers. See
\texttt{src/word\_source/editor\_words.c:74,188,202}.

\subsubsection{\texttt{VM\_HAS\_CURRENT\_ENTRY}}

Enables the \texttt{vm->current\_entry} field, which tracks the
currently-compiling word. Required for the SEE decompiler, recursive word
definitions, and dictionary introspection. Default: defined (enabled).

% ----------------------------------------------------------------
\subsection{Build System Variables}
\label{sec:build-vars}

\begin{itemize}
  \item \texttt{CC} — C compiler. Default: \texttt{gcc}. Also accepts \texttt{clang} and \texttt{aarch64-linux-gnu-gcc}.
  \item \texttt{CFLAGS} — compiler flags. Extends Makefile \texttt{BASE\_CFLAGS}.
  \item \texttt{LDFLAGS} — linker flags. Default includes \texttt{-Wl,--gc-sections -s -flto=auto -fuse-linker-plugin -static}.
  \item \texttt{MINIMAL} — integer (0 or 1). Setting \texttt{MINIMAL=1} enables \texttt{STARFORTH\_MINIMAL} and adds \texttt{-nostdlib -ffreestanding}.
  \item \texttt{ASM} — integer (0 or 1). When set to 1, the build emits \texttt{.s} assembly listings alongside \texttt{.o} object files.
\end{itemize}

% ----------------------------------------------------------------
\subsection{Build Configuration Matrix}
\label{sec:build-matrix}

\begin{table}[h]
\centering
\caption{Common build configurations}
\label{tab:build-matrix}
\begin{tabular}{llllll}
\toprule
Target & USE\_ASM\_OPT & USE\_DIRECT\_THREADING & NDEBUG & Opt level & Use case \\
\midrule
\texttt{debug}   & 0 & 0 & No  & \texttt{-O0 -g}          & Development, debugging \\
\texttt{all}     & 1 & 0 & No  & \texttt{-O2}             & Default build \\
\texttt{turbo}   & 1 & 0 & Yes & \texttt{-O3 -flto}       & Fast, no direct threading \\
\texttt{fast}    & 1 & 1 & Yes & \texttt{-O3}             & Fast, readable asm \\
\texttt{fastest} & 1 & 1 & Yes & \texttt{-O3 -flto}       & Maximum performance \\
\texttt{pgo}     & 1 & 1 & Yes & \texttt{-O3 -fprofile-use} & Absolute fastest \\
\texttt{minimal} & 0 & 0 & No  & \texttt{-O2}             & Embedded / bare-metal \\
\texttt{l4re}    & 0 & 0 & No  & \texttt{-O2}             & L4Re microkernel \\
\texttt{profile} & 0 & 0 & No  & \texttt{-O1 -g}          & Profiling \\
\bottomrule
\end{tabular}
\end{table}

% ----------------------------------------------------------------
\subsection{Optimization Level Guidelines}
\label{sec:build-optlevels}

\begin{itemize}
  \item \textbf{\texttt{-O0 -g} (development)} — fastest compile, slowest runtime (\(\approx\)10\(\times\) below optimized); full symbols, all assertions. Use for initial development and crash debugging.
  \item \textbf{\texttt{-O2} (balanced)} — moderate compile overhead; 3--4\(\times\) runtime gain over \texttt{-O0}. Default production-test builds.
  \item \textbf{\texttt{-O3} (high performance)} — aggressive inlining and vectorization; 5--6\(\times\) over \texttt{-O0}. Production releases.
  \item \textbf{\texttt{-O3 -flto -march=native -fprofile-use} (maximum)} — multi-stage build; 7--8\(\times\) over \texttt{-O0}. Release and benchmark artifacts. Use \texttt{make pgo}.
\end{itemize}

% ----------------------------------------------------------------
\subsection{Usage Examples}
\label{sec:build-examples}

\paragraph{Maximum performance native build}
\begin{lstlisting}[language=bash]
make clean && make pgo
\end{lstlisting}
Produces a PGO-optimized binary with assembly optimizations, direct threading,
and link-time optimization.

\paragraph{Debug build with profiler}
\begin{lstlisting}[language=bash]
make clean && make profile
./build/starforth --profile 3 --profile-report
\end{lstlisting}

\paragraph{Cross-compile for Raspberry Pi 4}
\begin{lstlisting}[language=bash]
make rpi4-cross
scp build/starforth pi@raspberrypi.local:~/
\end{lstlisting}
Produces a statically linked ARM64 binary optimized for Cortex-A72.

\paragraph{Minimal embedded build}
\begin{lstlisting}[language=bash]
make minimal
\end{lstlisting}
Produces a freestanding binary with no libc dependencies.

\paragraph{AMD Zen~3 custom build}
\begin{lstlisting}[language=bash]
make clean
make CFLAGS="$(BASE_CFLAGS) -O3 -march=znver3 \
     -DUSE_ASM_OPT=1 -DUSE_DIRECT_THREADING=1 -DNDEBUG" \
     LDFLAGS="-flto -s"
\end{lstlisting}

\paragraph{Generate assembly listings}
\begin{lstlisting}[language=bash]
make asm
less build/stack_management.s
\end{lstlisting}

% ----------------------------------------------------------------
\subsection{Compiler Support}
\label{sec:build-compilers}

\begin{itemize}
  \item \textbf{GCC} — recommended. Minimum GCC~7.0; GCC~11.0+ preferred for improved PGO and ARM64 code generation.
  \item \textbf{Clang} — minimum Clang~10.0; computed-goto and all assembly optimizations supported.
  \item \textbf{ARM64 cross-compilation from x86\_64:}
\end{itemize}

\begin{lstlisting}[language=bash]
sudo apt-get install gcc-aarch64-linux-gnu
make CC=aarch64-linux-gnu-gcc rpi4-cross
\end{lstlisting}

Static linking (\texttt{-static}) is recommended for cross-compiled binaries.

% ----------------------------------------------------------------
\subsection{Performance Tuning Checklist}
\label{sec:build-tuning}

For maximum throughput:

\begin{itemize}
  \item Use \texttt{make pgo} (profile-guided optimization).
  \item Enable \texttt{USE\_ASM\_OPT=1} and \texttt{USE\_DIRECT\_THREADING=1}.
  \item Define \texttt{NDEBUG}.
  \item Pass \texttt{-O3 -flto -march=native}.
  \item Add \texttt{-fno-plt -fno-semantic-interposition} to reduce indirection.
  \item Add \texttt{-funroll-loops -finline-functions} for code expansion.
  \item Link statically (\texttt{-static}) to eliminate PLT overhead.
  \item Strip symbols (\texttt{-s}) to reduce binary size.
\end{itemize}

Expected result: \(\approx\)7--8\(\times\) faster than a debug build;
\(\approx\)1.2--1.5\(\times\) faster than a plain \texttt{-O3} build.

% ----------------------------------------------------------------
\subsection{Troubleshooting}
\label{sec:build-trouble}

\paragraph{``Unknown architecture'' warning}
The build falls back automatically to pure-C implementations. Assembly
optimizations are disabled. To add support for a new architecture, extend
\texttt{arch\_detect.h}.

\paragraph{Direct threading shows no performance gain}
Verify that both \texttt{USE\_DIRECT\_THREADING=1} and \texttt{USE\_ASM\_OPT=1}
are set, that the target is x86\_64 or ARM64, and that the compiler is GCC or
Clang. At runtime, \texttt{WORDS-INFO} reports whether direct threading is
active.

\paragraph{PGO coverage mismatch warnings}
Run \texttt{make clean \&\& make pgo} to force a full clean two-stage rebuild.
Stale coverage data from a prior instrumentation pass causes these warnings.