micheleandCursor
9f76ab9e74
Clear doc-block warnings so doxygen exits 0, add GitHub Actions for host tests, Doxygen, and manual sync, and document CI in the manual. Co-authored-by: Cursor <cursoragent@cursor.com>
92 lines
2.9 KiB
TeX
92 lines
2.9 KiB
TeX
\chapter{Building and Flashing}
|
|
\label{ch:build}
|
|
|
|
The firmware is built with ESP-IDF; the hardware-free domain core also
|
|
builds and is unit-tested on the host machine.
|
|
|
|
\section{Toolchain}
|
|
|
|
\begin{table}[htbp]
|
|
\centering
|
|
\begin{tabular}{@{}ll@{}}
|
|
\drhead Item & Choice \\
|
|
\midrule
|
|
Framework & ESP-IDF v5.5.x (native) \\
|
|
Language & C++23 (\texttt{-std=gnu++23}) \\
|
|
Error model & \texttt{std::expected}; exceptions off \\
|
|
Documentation & Doxygen (build must pass) \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\caption{Firmware toolchain.}
|
|
\label{tab:build-toolchain}
|
|
\end{table}
|
|
|
|
\section{Device build}
|
|
|
|
\begin{drcode}[Build, flash, monitor]
|
|
idf.py set-target esp32s3
|
|
idf.py build
|
|
idf.py -p <port> flash monitor
|
|
\end{drcode}
|
|
|
|
\section{Host unit tests}
|
|
|
|
The pure core is tested on the host, with no board attached. On macOS the
|
|
tests need a C++23 standard library --- use a Homebrew LLVM (>= 18) or
|
|
GCC~14 rather than the system Apple Clang.
|
|
|
|
\begin{drcode}[Host tests]
|
|
cmake -S components/core/test -B build-host \
|
|
-DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++"
|
|
cmake --build build-host
|
|
ctest --test-dir build-host --output-on-failure
|
|
\end{drcode}
|
|
|
|
\section{Documentation}
|
|
|
|
Documentation has two enforced checks, run from the \texttt{Software/}
|
|
directory:
|
|
|
|
\begin{enumerate}
|
|
\item \textbf{Doxygen} --- C++ API reference from source doc blocks.
|
|
An undocumented public class, method, or parameter fails the build.
|
|
\item \textbf{Manual sync} --- every public class under an
|
|
\texttt{include/} tree must have a matching
|
|
\texttt{\textbackslash label\{cls:ClassName\}} section in
|
|
\texttt{docs/manual/ch-classes.tex}. Design-level HTTP API
|
|
documentation lives in Chapter~\ref{ch:api}.
|
|
\end{enumerate}
|
|
|
|
\begin{drcode}[Docs (from Software/)]
|
|
doxygen Doxyfile
|
|
python3 tools/check-manual-sync.py
|
|
\end{drcode}
|
|
|
|
\section{Continuous integration}
|
|
|
|
Every push and pull request to \texttt{main} runs
|
|
\texttt{.github/workflows/ci.yml} at the repository root (three parallel
|
|
jobs, all from the \texttt{Software/} directory):
|
|
|
|
\begin{enumerate}
|
|
\item \textbf{Host tests} --- \texttt{cmake} + \texttt{ctest} on
|
|
\texttt{components/core/test} (C++23, \texttt{g++-14} on Ubuntu).
|
|
\item \textbf{Doxygen} --- must exit 0 with an empty
|
|
\texttt{docs/api/doxygen-warnings.log}.
|
|
\item \textbf{Manual sync} --- \texttt{tools/check-manual-sync.py}.
|
|
\end{enumerate}
|
|
|
|
To rebuild the PDF manual (requires a LaTeX installation):
|
|
|
|
\begin{drcode}[Manual PDF]
|
|
cd docs/manual
|
|
latexmk -lualatex manual.tex
|
|
\end{drcode}
|
|
|
|
\begin{drcaution}[Keep it green]
|
|
Both checks are part of the definition of done. A firmware change that
|
|
adds or modifies a public class, a REST endpoint, or its behaviour must
|
|
update the Doxygen doc blocks, \texttt{ch-classes.tex} (for classes), and
|
|
\texttt{ch-api.tex} (for HTTP) in the same change.
|
|
\end{drcaution}
|