rajamesandJunie
a8b70e88d3
Source tree reorganization: - Move StarForth v3 engine to v3/ (src/, include/, Makefile) - Move kernel to kernel/ (src/, include/, linker/, Makefile) - Create v4/ skeleton for F18-ISA golden model (DECOMPOSITION.md, JUSTIFICATION.md) - Move FABRIC-0..4.md to docs/fabric/ - Move ONTOLOGY.md and ROADMAP.md to docs/ Board infrastructure: - Add boards/ser5/, boards/raspi/, boards/milkv/, boards/zynq7020/ - Each board has board.mk (ISA, CPU flags, boot recipe) and README.md - Root Makefile becomes thin dispatcher: boot_image, all, clean, docs take TARGET - make boot_image TARGET=SER5|RASPI|MILKV builds one GPT/MBR image per board - ZYNQ7020 target exists but stops with clear error (ARMv7 port not built yet) - scripts/mkdiskimage.sh builds disk images for all boards Docs pipeline: - docs/book/ with LaTeX master (main.tex) and Makefile - pandoc converts Markdown to LaTeX at build time - Two Lua filters: table-widths.lua (wide tables wrap), code-breaks.lua (inline code breaks) - make docs builds single PDF (754 pages, 0 missing characters) - make docs TARGET=<board> adds board appendix - build/docs/<book|board>/meta.tex stamps git commit into PDF Bug fixes: - 42 include paths that only worked by accident now use correct relative paths - clang-18 hardcode replaced with configurable CC variable (fixed aarch64 build) - Pi 5: kernel_2712.img linked at 0x80000, .bss zeroed, memory reserved - Doxyfile, .clang-tidy, README.md, Kconfig paths updated Verified: - Hosted v3 build passes 1012 tests, 0 failures - SER5 image boots in QEMU (OVMF), POST passes, K exact (65536 = Q48_ONE) - Milk-V image boots in QEMU (OpenSBI + U-Boot + bootefi), POST passes - make clean TARGET=<board> removes only that board and its ISA objects - make all builds all boards, hosted v3, and docs in one run Co-authored-by: Junie <junie@jetbrains.com>
67 lines
3.7 KiB
Markdown
67 lines
3.7 KiB
Markdown
# docs/book/
|
|
|
|
`make docs` builds one PDF, `build/docs/LithosAnanke.pdf`, from `main.tex` with xelatex.
|
|
`make docs TARGET=<board>` builds `build/docs/LithosAnanke-<board>.pdf`: the same book with
|
|
`boards/<board>/README.md` added as an appendix.
|
|
|
|
Tools: `sudo apt-get install -y pandoc latexmk texlive-xetex texlive-latex-extra texlive-pictures texlive-fonts-recommended fonts-dejavu fonts-dejavu-extra`
|
|
|
|
Without root, a user-local TeX Live works too (this is how the book was first built):
|
|
TinyTeX (`curl -sL https://yihui.org/tinytex/install-bin-unix.sh | sh`) plus
|
|
`tlmgr install latexmk xetex fontspec pgf pgfplots booktabs multirow fancyvrb fvextra lineno upquote ulem enumitem newunicodechar bookmark hyperref geometry xcolor graphics tools etoolbox fancyhdr truncate amsfonts`,
|
|
and the pandoc release tarball unpacked into `~/.local`.
|
|
|
|
The installed DejaVu decides italics: `fonts-dejavu-core` alone has no serif italic, so
|
|
`main.tex` falls back to a slanted upright face; `fonts-dejavu-extra` gives real italics.
|
|
|
|
## How it fits together
|
|
|
|
- `main.tex` is the master file. It sets the parts and the chapter order.
|
|
- Chapters that are still Markdown are listed in `Makefile` (`CHAPTERS`, as `name:source.md`).
|
|
At build time pandoc converts each one into `build/docs/gen/<name>.tex`, and `main.tex`
|
|
includes it with `\input{<name>}`. The Markdown stays the source until the chapter is
|
|
rewritten in LaTeX. At that point the `.tex` moves into this directory and the `CHAPTERS`
|
|
entry is removed.
|
|
- `pandoc/highlighting.latex` extracts the code-highlighting macros from the installed pandoc,
|
|
so the macros and the fragments always come from the same pandoc version.
|
|
- Two Lua filters run on every chapter. `pandoc/table-widths.lua` gives wide tables
|
|
proportional wrapping columns, because pandoc's gfm reader leaves column widths unset.
|
|
`pandoc/code-breaks.lua` lets long inline identifiers and paths break after `_ / . - :`.
|
|
Code blocks wrap through fvextra (`breaklines`).
|
|
- `build/docs/<book|board>/meta.tex` is written on every build. It records the commit (and
|
|
whether there were uncommitted changes), the date, and the board.
|
|
|
|
## Rule for data
|
|
|
|
Any figure or table that shows measured numbers is generated from the CSV when the book is
|
|
built. Numbers are never typed in by hand:
|
|
|
|
```latex
|
|
\begin{tikzpicture}
|
|
\begin{axis}[xlabel=run, ylabel=K]
|
|
\addplot table[col sep=comma, x=run, y=K]{experiments/<campaign>/results.csv};
|
|
\end{axis}
|
|
\end{tikzpicture}
|
|
\datasource{experiments/<campaign>/results.csv}
|
|
```
|
|
|
|
Use `\pgfplotstabletypeset[col sep=comma]{...}` for tables. `\datasource` prints the CSV path
|
|
and the commit, so a reader can find the exact file the figure was drawn from. CSV paths are
|
|
repo-relative, because xelatex runs from the repo root.
|
|
|
|
## Older pipelines to fold in or retire
|
|
|
|
These still exist and still have their own targets. Each one needs a decision during the
|
|
curation pass: move it into this book, or retire it.
|
|
|
|
| Source | Current target | Produces |
|
|
|---|---|---|
|
|
| `docs/formal/vol1-vm-physics`, `vol2-kernel`, `vol3-research` | `make -C docs/formal vols` | three volume PDFs |
|
|
| `docs/formal/dev-guide`, `user-guide`, `cookbook` | `make -C docs/formal books` | three practitioner PDFs |
|
|
| `docs/formal/experiments`, `proofs`, `ssrn`, `patent` | `make -C docs/formal standalone` | four standalone PDFs |
|
|
| Doxygen (`Doxyfile`) | `make -C docs/formal doxygen` | API reference PDF |
|
|
| `scripts/generate-doxygen-appendix.sh` | `make -f v3/Makefile api-docs` | AsciiDoc API appendix |
|
|
| `docs/src/internal/formal/*.thy` | `make -f v3/Makefile docs-isabelle` | Isabelle report |
|
|
| `scripts/asciidoc-to-latex.sh` | `make -f v3/Makefile docs-latex` | `docs/latex/` |
|
|
| `docs/SSRN_companion/Math_Companion_SSRN.tex` | `make -f v3/Makefile math-companion` | SSRN math companion |
|