128 lines
4.8 KiB
TeX
128 lines
4.8 KiB
TeX
%% SCRAP: architecture/getting-started/DEVELOPER
|
|
%% SOURCE: docs/working/architecture/getting-started/DEVELOPER.md
|
|
%% STATUS: CURRENT
|
|
%% FITS: dev-guide/ch-install
|
|
%% EDITORIAL: lifted — prose rewritten to press voice
|
|
|
|
\section{Developer Environment}
|
|
|
|
This chapter sets up a working StarForth development environment, including the
|
|
Isabelle/HOL toolchain required to regenerate the formal-verification
|
|
documentation.
|
|
|
|
\subsection{Required Tools}
|
|
|
|
The core build needs only a C toolchain and Git:
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
sudo apt-get update
|
|
sudo apt-get install build-essential gcc make git
|
|
\end{lstlisting}
|
|
|
|
Several optional tools support documentation, supply-chain, and packaging
|
|
workflows: Doxygen for API documentation, \texttt{syft} for SBOM generation,
|
|
and \texttt{fpm} for building DEB and RPM packages.
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
sudo apt-get install doxygen
|
|
|
|
wget https://github.com/anchore/syft/releases/latest/download/syft_linux_amd64.tar.gz
|
|
tar -xzf syft_linux_amd64.tar.gz
|
|
sudo mv syft /usr/local/bin/
|
|
|
|
sudo apt-get install ruby-dev build-essential
|
|
sudo gem install fpm
|
|
\end{lstlisting}
|
|
|
|
\subsection{Isabelle/HOL}
|
|
|
|
Isabelle is required to generate the formal-verification documentation.
|
|
Download Isabelle2025, unpack it, and place its \texttt{bin} directory on the
|
|
\texttt{PATH}:
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
cd ~/bin
|
|
wget https://isabelle.in.tum.de/dist/Isabelle2025_linux.tar.gz
|
|
tar -xzf Isabelle2025_linux.tar.gz
|
|
\end{lstlisting}
|
|
|
|
Add the binaries to \texttt{\textasciitilde/.bashrc}, reload the shell, and
|
|
verify:
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
export PATH="$PATH:$HOME/bin/Isabelle2025/bin"
|
|
source ~/.bashrc
|
|
isabelle version # expects: Isabelle2025
|
|
\end{lstlisting}
|
|
|
|
The build system locates Isabelle on the \texttt{PATH} via a single Makefile
|
|
variable, \texttt{ISABELLE ?= isabelle}. Isabelle is deliberately excluded from
|
|
the repository through \texttt{.gitignore} (\texttt{/tools/Isabelle2025/}) and
|
|
must never be committed. With it installed, three targets become available:
|
|
\texttt{make isabelle-build} verifies all theories, \texttt{make isabelle-check}
|
|
runs a faster syntax-only pass, and \texttt{make docs-isabelle} produces the
|
|
audit-ready documentation.
|
|
|
|
\subsection{Continuous Integration}
|
|
|
|
CI pipelines must install Isabelle as a build step. A GitHub Actions job
|
|
installs the C toolchain, fetches and unpacks Isabelle, appends its
|
|
\texttt{bin} directory to \texttt{\$GITHUB\_PATH}, builds with \texttt{make
|
|
fastest}, runs \texttt{make test}, and generates the verification docs with
|
|
\texttt{make docs-isabelle} before uploading them as artifacts. The GitLab
|
|
equivalent performs the same steps in a \texttt{before\_script} stage.
|
|
|
|
\subsubsection{Docker and Performance}
|
|
|
|
In Docker, Isabelle additionally requires a JDK (17 or later):
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
FROM ubuntu:22.04
|
|
RUN apt-get update && apt-get install -y \
|
|
build-essential gcc make wget openjdk-17-jdk \
|
|
&& rm -rf /var/lib/apt/lists/*
|
|
RUN wget -q https://isabelle.in.tum.de/dist/Isabelle2025_linux.tar.gz && \
|
|
tar -xzf Isabelle2025_linux.tar.gz && rm Isabelle2025_linux.tar.gz
|
|
ENV PATH="/Isabelle2025/bin:${PATH}"
|
|
RUN isabelle version
|
|
\end{lstlisting}
|
|
|
|
Full theory verification takes five to ten minutes. Cache the Isabelle
|
|
installation between builds, use \texttt{isabelle-check} for fast pre-commit
|
|
syntax checks, and reserve the full \texttt{isabelle-build} for the main branch
|
|
and release tags.
|
|
|
|
\subsection{Quick Start}
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
git clone <repo-url>
|
|
cd StarForth
|
|
make fastest
|
|
make test
|
|
make docs-isabelle
|
|
ls -la docs/src/isabelle/
|
|
\end{lstlisting}
|
|
|
|
\subsection{Formal Verification}
|
|
|
|
StarForth carries machine-checked correctness proofs in Isabelle/HOL. The
|
|
theory files live under \texttt{docs/src/internal/formal/*.thy}, organized into
|
|
the \texttt{VM\_Formal} and \texttt{Physics\_Formal} sessions, and
|
|
\texttt{make docs-isabelle} renders them into \texttt{docs/src/isabelle/}. The
|
|
session covers core VM semantics (\texttt{VM\_Core.thy}), stack operations and
|
|
runtime (\texttt{VM\_Stacks.thy}, \texttt{VM\_StackRuntime.thy}), word and
|
|
register definitions (\texttt{VM\_Words.thy},
|
|
\texttt{VM\_DataStack\_Words.thy}, \texttt{VM\_ReturnStack\_Words.thy},
|
|
\texttt{VM\_Register.thy}), and the physics state machine and observation model
|
|
(\texttt{Physics\_StateMachine.thy}, \texttt{Physics\_Observation.thy}). All
|
|
theories are fully verified.
|
|
|
|
%% TODO(bob): the repository .thy filenames here (VM_Core.thy etc.) differ from the proof/ tree named in CLAUDE.md (StarForth_*.thy). Reconcile the canonical theory-file naming before this ships.
|
|
|
|
\subsection{Contributing}
|
|
|
|
When a change affects VM semantics: update the relevant Isabelle theories, run
|
|
\texttt{make isabelle-build} to verify the proofs, regenerate documentation
|
|
with \texttt{make docs-isabelle}, and include the regenerated docs in the pull
|
|
request.
|