70 lines
3.0 KiB
TeX
70 lines
3.0 KiB
TeX
%% SCRAP: scratch/AGENTS
|
|
%% SOURCE: docs/working/scratch/AGENTS.md
|
|
%% STATUS: HISTORICAL
|
|
%% FITS: none
|
|
%% EDITORIAL: lifted — prose rewritten to press voice
|
|
|
|
\section{Repository Guidelines for Contributors}
|
|
|
|
This document records the contributor guidelines that were in effect during
|
|
active development. It is preserved as a historical record of coding and
|
|
workflow conventions. See \texttt{.claude/CLAUDE.md} for the current
|
|
authoritative reference.
|
|
|
|
\subsection{Project Structure}
|
|
|
|
\texttt{src/} holds the VM core; \texttt{src/platform/} handles host glue
|
|
and timing; \texttt{src/word\_source/} groups FORTH words by domain using the
|
|
\texttt{<area>\_words.c} pattern with matching headers in
|
|
\texttt{src/word\_source/include/}. \texttt{include/} is the public boundary;
|
|
keep helpers and private state in \texttt{src/} to avoid symbol drift.
|
|
\texttt{src/test\_runner/} holds the in-process harness and module suites.
|
|
The \texttt{build/} directory is disposable output.
|
|
|
|
\subsection{Build and Development Commands}
|
|
|
|
\begin{itemize}
|
|
\item \texttt{make} — default optimized build; binary in
|
|
\texttt{build/<arch>/standard/starforth}.
|
|
\item \texttt{make fastest} — release build with LTO/asm fast paths; use
|
|
for performance validation.
|
|
\item \texttt{make debug} — \texttt{-O0 -g}; run \texttt{make clean}
|
|
before switching profiles.
|
|
\item \texttt{make test} — full harness via piped BYE.
|
|
\item \texttt{make bench} — microbench; helpful before pushing hot-path
|
|
changes.
|
|
\end{itemize}
|
|
|
|
\subsection{Coding Style}
|
|
|
|
Strict ANSI C99, four-space indentation, same-line braces. Use
|
|
\texttt{snake\_case} for functions and variables, uppercase for macros, and
|
|
\texttt{g\_} prefixes for file-scoped statics. Exported APIs in
|
|
\texttt{include/} carry concise doc headers; internals default to
|
|
\texttt{static}. All builds must be warning-clean (\texttt{-Wall -Wextra
|
|
-Werror}). Gate new behavior behind existing flags.
|
|
|
|
\subsection{Testing}
|
|
|
|
Add suites in \texttt{src/test\_runner/modules/} with a
|
|
\texttt{run\_<area>\_tests} entry; register in \texttt{test\_runner.c}. Run
|
|
\texttt{make test} before all pull requests. When touching public APIs or hot
|
|
paths, add coverage alongside the change and note performance measurements.
|
|
|
|
\subsection{Commit and Pull Request Guidelines}
|
|
|
|
Sentence-style subjects under 72 characters, narrowly scoped commits,
|
|
rationale and key flags in the body. Pull requests must state intent,
|
|
verification commands (\texttt{make test}, \texttt{make bench}), and any
|
|
configuration or documentation updates. Do not edit generated assets in
|
|
\texttt{build/} or hand-edit seeded configs; use existing scripts to
|
|
regenerate. Flag platform-specific changes early so relevant subsystem
|
|
reviewers can weigh in.
|
|
|
|
\subsection{Security and Configuration}
|
|
|
|
Treat \texttt{conf/} seeds as shared fixtures — copy before experiments and
|
|
regenerate via scripts rather than editing in place. Follow existing
|
|
cleanup/ownership patterns when adding platform code to prevent resource
|
|
leaks in long-running benchmarks.
|