204 lines
6.5 KiB
TeX
204 lines
6.5 KiB
TeX
%% SCRAP: architecture/getting-started/QUICKSTART
|
|
%% SOURCE: docs/working/architecture/getting-started/QUICKSTART.adoc
|
|
%% STATUS: CURRENT
|
|
%% FITS: dev-guide/ch-install, user-guide/ch-quickstart
|
|
%% EDITORIAL: lifted — prose rewritten to press voice; emoji stripped
|
|
|
|
\section{Quick Start}
|
|
\label{sec:quickstart}
|
|
|
|
Build the fastest binary for the current platform:
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
make fastest
|
|
\end{lstlisting}
|
|
|
|
% -----------------------------------------------------------------------
|
|
\subsection{Common Build Commands}
|
|
\label{sec:quickstart-commands}
|
|
|
|
\begin{table}[h]
|
|
\centering
|
|
\begin{tabular}{lll}
|
|
\toprule
|
|
Command & What it does & When to use \\
|
|
\midrule
|
|
\texttt{make fastest} & Maximum speed build & Production, benchmarking \\
|
|
\texttt{make fast} & Fast without LTO & Development, debugging \\
|
|
\texttt{make debug} & Debug build (-g -O0) & Debugging with GDB \\
|
|
\texttt{make benchmark} & Run full benchmark suite & Performance testing \\
|
|
\texttt{make help} & List all options & Reference \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\caption{Common StarForth build commands.}
|
|
\label{tab:quickstart-commands}
|
|
\end{table}
|
|
|
|
% -----------------------------------------------------------------------
|
|
\subsection{Platform-Specific Builds}
|
|
\label{sec:quickstart-platforms}
|
|
|
|
\subsubsection{x86\_64 Linux}
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
make fastest # Auto-detects x86_64; builds with ASM optimisations
|
|
./build/starforth
|
|
\end{lstlisting}
|
|
|
|
\subsubsection{Raspberry~Pi~4 (native)}
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
make fastest # Auto-detects ARM64; optimised for Cortex-A72
|
|
./build/starforth
|
|
\end{lstlisting}
|
|
|
|
\subsubsection{Raspberry~Pi~4 (cross-compile from x86\_64)}
|
|
|
|
Requires \texttt{gcc-aarch64-linux-gnu}:
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
make rpi4-cross # Builds ARM64 binary with inline ASM
|
|
scp build/starforth pi@raspberrypi.local:~/
|
|
\end{lstlisting}
|
|
|
|
The resulting binary is statically linked and requires no runtime dependencies
|
|
on the target device.
|
|
|
|
% -----------------------------------------------------------------------
|
|
\subsection{Performance Modes}
|
|
\label{sec:quickstart-perf}
|
|
|
|
Build targets are ranked by output speed:
|
|
|
|
\begin{enumerate}
|
|
\item \texttt{make pgo} — Profile-Guided Optimisation; 5--15\% faster than
|
|
\texttt{fastest}; requires two build passes (3--5 minutes).
|
|
\item \texttt{make fastest} — Recommended for production; ASM optimisations,
|
|
direct threading, LTO.
|
|
\item \texttt{make fast} — ASM + direct threading; no LTO; easier to
|
|
instrument.
|
|
\item \texttt{make turbo} — ASM optimisations only; no direct threading.
|
|
\item \texttt{make all} — Standard build (\texttt{-O2}).
|
|
\item \texttt{make debug} — No optimisations (\texttt{-O0}); full debug
|
|
symbols.
|
|
\end{enumerate}
|
|
|
|
% -----------------------------------------------------------------------
|
|
\subsection{INIT System}
|
|
\label{sec:quickstart-init}
|
|
|
|
At startup StarForth automatically loads \texttt{./conf/init.4th}, which
|
|
defines the foundational word set. No configuration is required:
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
./build/starforth
|
|
ok> # Words from init.4th are immediately available
|
|
\end{lstlisting}
|
|
|
|
\texttt{init.4th} defines words, installs a dictionary fence to protect them
|
|
from \texttt{FORGET}, and zeros blocks for user use.
|
|
|
|
% -----------------------------------------------------------------------
|
|
\subsection{Testing and Benchmarking}
|
|
\label{sec:quickstart-test}
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
make bench # Quick benchmark (1 million operations)
|
|
make benchmark # Full benchmark suite
|
|
make test # Run full test suite (936+ tests)
|
|
\end{lstlisting}
|
|
|
|
Typical performance for 1~million stack operations:
|
|
|
|
\begin{table}[h]
|
|
\centering
|
|
\begin{tabular}{lll}
|
|
\toprule
|
|
Build type & x86\_64 & ARM64 (Raspberry~Pi~4) \\
|
|
\midrule
|
|
Debug & $\sim$800\,ms & $\sim$1200\,ms \\
|
|
Standard & $\sim$250\,ms & $\sim$380\,ms \\
|
|
Fastest & $\sim$60\,ms & $\sim$95\,ms \\
|
|
PGO & $\sim$50\,ms & $\sim$80\,ms \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\caption{StarForth benchmark timings (1M stack operations).}
|
|
\label{tab:quickstart-bench}
|
|
\end{table}
|
|
|
|
% -----------------------------------------------------------------------
|
|
\subsection{Flags Enabled by \texttt{make fastest}}
|
|
\label{sec:quickstart-flags}
|
|
|
|
\begin{table}[h]
|
|
\centering
|
|
\begin{tabular}{ll}
|
|
\toprule
|
|
Flag & Effect \\
|
|
\midrule
|
|
\texttt{-O3} & Maximum compiler optimisation \\
|
|
\texttt{-march=native} (x86\_64) & Use all host CPU features \\
|
|
\texttt{-march=armv8-a+crc+simd} (ARM64) & ARMv8 with NEON \\
|
|
\texttt{-DUSE\_ASM\_OPT=1} & Assembly optimisations \\
|
|
\texttt{-DUSE\_DIRECT\_THREADING=1} & Direct-threaded interpreter \\
|
|
\texttt{-flto} & Link-Time Optimisation \\
|
|
\texttt{-funroll-loops} & Loop unrolling \\
|
|
\texttt{-finline-functions} & Aggressive function inlining \\
|
|
\texttt{-fomit-frame-pointer} & Free register for execution \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\caption{Compiler flags active in \texttt{make fastest}.}
|
|
\label{tab:quickstart-flags}
|
|
\end{table}
|
|
|
|
% -----------------------------------------------------------------------
|
|
\subsection{Advanced Build Options}
|
|
\label{sec:quickstart-advanced}
|
|
|
|
Custom compiler flags:
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
make fastest CFLAGS="$(make -s print-cflags) -DCUSTOM_FLAG"
|
|
\end{lstlisting}
|
|
|
|
Static binary:
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
make fastest LDFLAGS="-static -s"
|
|
\end{lstlisting}
|
|
|
|
Alternate compiler:
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
make fastest CC=clang
|
|
\end{lstlisting}
|
|
|
|
% -----------------------------------------------------------------------
|
|
\subsection{Troubleshooting}
|
|
\label{sec:quickstart-trouble}
|
|
|
|
\paragraph{Illegal instruction error}
|
|
The host CPU does not support a required optimisation. Use a conservative
|
|
baseline:
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
make fastest CFLAGS="$(BASE_CFLAGS) -O3 -march=x86-64 -DUSE_ASM_OPT=1"
|
|
\end{lstlisting}
|
|
|
|
\paragraph{Build fails outright}
|
|
Verify the standard build first, then re-enable optimisations incrementally:
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
make clean && make all
|
|
make clean && make fast
|
|
make clean && make fastest
|
|
\end{lstlisting}
|
|
|
|
\paragraph{Slow performance}
|
|
Confirm optimisation symbols are present in the binary:
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
file build/starforth
|
|
nm build/starforth | grep vm_push_asm
|
|
\end{lstlisting}
|