diff --git a/CLAUDE.md b/CLAUDE.md index e4b417b..69b059b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -65,7 +65,17 @@ else, pick the simplest thing that passes the fixtures and note the choice in th ## Don't reinvent -- Per-macro profiling → point at `texprof` (TeX Live, pdfTeX only). prumo stays at package/file/page. +- Per-macro profiling → point at `texprof` (TeX Live's `hitex` package). It is its own engine + (TeX + e-TeX + Prote) and writes DVI, so it measures itself, not pdfTeX, XeTeX or LuaTeX. + prumo stays at package/file/page. +- Static checks without a build (unused definitions, preamble cost) → `SaTeX`. prumo measures + a real build. +- Package lookup by file, command or environment name → `texfindpkg`. `packages` starts from a + build, not from names. +- A `DEPENDS.txt` for minimal installs → `DEPP` (Island of TeX) writes one from a `file/before` + hook. Read it before giving `packages` a dependency-file output. +- Precompiled preambles, draft mode, TikZ externalization → `mylatexformat`, `-draftmode` (or + `-no-pdf`) and tikz's external library. `whatif` measures them and never reimplements them. - Log parsing for file nesting → read how `texlogsieve` does it before writing a log parser; prumo prefers hook records and uses the log only as a cross-check. - Build orchestration → `latexmk`. prumo wraps it (`-usepretex`, `-jobname`), never replaces it. diff --git a/README.md b/README.md index b3ad77c..7eb8ec8 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,10 @@ in performance and in optimization, and prumo is how I look inside a LaTeX build instrumented build shows where the time goes, which package loaded which, and what you can drop. +Most of the individual pieces already exist in other tools, and [Related tools](#related-tools) +names them. prumo puts them behind one instrumented build on the stock pdfTeX, XeTeX and +LuaTeX engines. + It has been run on my own corpus and on public documents from an ACM paper to the 7,710-page Stacks Project (see [the benchmarks](docs/benchmarks/README.md)). Please report what breaks! @@ -263,8 +267,12 @@ TEXINPUTS=tex: pdflatex -recorder -jobname=main "\RequirePackage{prumo}\PrumoEnv It only listens to the LaTeX hook management system and writes one event per line to `main.prumo`: files, packages and classes opening and closing, the steps of `\begin{document}` and `\end{document}`, each shipout, and the environments it was asked to -watch. It never changes typesetting: the PDF is byte-identical with and without it, on all -three engines, and that is a test. prumo reads that record, the engine's `-recorder` file list +watch. It never changes typesetting. A test builds each fixture twice, once plain and once +with the probe, and compares the two PDFs byte for byte, with nothing skipped. Both builds run +in the same directory, because LuaTeX's `/ID` depends on the output path, and with +`SOURCE_DATE_EPOCH=0` and `FORCE_SOURCE_DATE=1`, so the dates in the PDF and from `\today` are +fixed. That is eight fixtures, seven of them on all three engines and the fontspec one on +XeTeX. prumo reads that record, the engine's `-recorder` file list (`main.fls`) and the PDF into one model and reports from there. The reference analyzer, `scripts/prumo_report.py`, is the oracle the Rust implementation must @@ -316,19 +324,26 @@ seconds longer; `compare` runs every engine twice for that reason, and the - **Package and page, not macro.** For per-line and per-macro profiling there is `texprof` (below). prumo answers the questions before that one: which package, which file, which page, which environment, which font, which `\usepackage` line. -- **Experiments, not guesses.** "Unused" means the document was rebuilt without the request and +- **Experiments.** "Unused" means the document was rebuilt without the request and nothing observable changed: page count, text, a coarse render. The caveat is printed with it. ## Related tools These are the tools I know of that touch the same questions. Each was installed and run on -TeX Live 2026 (November 2026) before I described it here. +TeX Live 2026 (November 2026) before I described it here, except DEPP, which I have read but +not run. - **texprof and texprofile** (Martin Ruckert, TUGboat 45:2, 2024; in TeX Live, in the `hitex` package). texprof is a TeX engine of its own, Knuth's TeX with e-TeX and Prote, and it writes DVI. It timestamps every command and charges the time to the file and line the command came from, a macro's to where it was defined. texprofile prints the tables and a call graph. +- **SaTeX** (Florian Sihler, Rust, 0.2.2 of November 2026, on crates.io; its README says it is + still work in progress). An abstract interpreter for TeX and LaTeX: it expands macros and + runs primitives, and it does not typeset. `satex lint` has a `preamble-cost` note, an + `unused-package` hint (nothing the package defines is used), and `missing-dependency` and + `unused-dependency` checks against a `DEPENDS.txt`. `--timings` breaks SaTeX's own run down + by phase and file, not the engine's. - **latexpkges3** (Python, on PyPI since 2021, a fork of LaTeXpkges from 2015). Removes each `\usepackage` in the main file's preamble in turn, rebuilds, and compares an MD5 of the output. By design it looks only at the main file's top level. @@ -348,12 +363,44 @@ TeX Live 2026 (November 2026) before I described it here. found" errors name, until the build gets through. - **mkjobtexmf** (Heiko Oberdiek, 2011, in TeX Live). Collects the files one run read, from `-recorder` or strace, into a texmf tree for that job. - -prumo's answers come from hooks on the build you already run, on any of the three engines. -The package graph is what the hooks saw load, not what the source text names. `unused` -compares page count, text and a coarse render, not a checksum or an exit code. The package -list is the files the engine read, mapped through your `texlive.tlpdb`. The installers above -add what is missing; `prune` subtracts what a corpus does not use. +- **DEPP** (Marei Peischl, Island of TeX, 0.4 of January 2026, on GitLab and not yet on CTAN; + not run). A package loaded ahead of the document. On each `file/before` hook it names the + file's TeX Live package from where the file sits in the tree, asks `tlmgr search --file` + through shell-escape for the rest, and writes the list to `DEPENDS.txt` for a minimal Docker + image or a Nix `texlive.withPackages`. Its documentation says it works with LuaLaTeX and + that the other engines are in progress. +- **pdffonts** (Poppler). Lists the fonts in a PDF with their type and encoding, and whether + each one is embedded and subset. + +### Same idea as existing tools + +Where prumo does what one of the tools above already does: + +- `unused`: remove the request, rebuild, compare the output. LaTeXpkges did it in 2015, and + latexpkges3 and stygtfo do it too. SaTeX's `unused-package` asks the same question from its + analysis, without a build. +- `graph`: a package dependency graph with Graphviz output, as latex-dependency-grapher draws. +- `packages`: the files a run read (`-recorder`), mapped to TeX Live packages. mkjobtexmf + collects the same file list. Joseph Wright described the same `.fls`-to-package lookup on + the [tex-live list](https://tug.org/pipermail/tex-live/2024-April/050431.html) in April 2024 + and posted it as a [script on TeX.SE](https://tex.stackexchange.com/a/716373). DEPP builds + its list from a `file/before` hook, as prumo's probe does. +- `prune`: a small install for a set of documents. TinyTeX and texliveonfly get there by + adding, mkjobtexmf by building a per-job tree, and DEPP by writing the list to install. +- `fonts`: the embedded side is pdffonts output. +- `time`: per-page timing with `\pdfelapsedtime` is a known technique, from a + [2014 TeX.SE answer](https://tex.stackexchange.com/a/211572). texprof goes finer, to the line + and the macro. +- `whatif`: a preamble precompiled with mylatexformat, draft mode and TikZ externalization are + existing techniques. prumo only measures them. + +### What differs + +- The answers come from hooks on the build you already run, on any of the three engines. +- The package graph is what the hooks saw load, not what the source text names. +- `unused` compares page count, text and a coarse render, not a checksum or an exit code. +- The package list is the files the engine read, mapped through your `texlive.tlpdb`. +- The installers above add what is missing; `prune` subtracts what a corpus does not use. ### Why not texprof @@ -366,12 +413,22 @@ package of hooks on the engine you already use, so the numbers are your build's, of packages, files, pages and environments. When prumo points at a package and you want to know which of its macros, that is texprof's question. +## Built on + +- The LaTeX hook management system (`\AddToHook`), which the probe listens to. +- expl3's `\sys_timer:`, the timer in every record. +- The engines' `-recorder` file list. +- `texlive.tlpdb`, TeX Live's package database, for `packages` and `prune`. +- The Poppler tools: `pdffonts`, `pdftotext`, `pdftoppm` and `pdfinfo`. +- latexmk, which drives the build with `--latexmk`. +- mylatexformat, for the precompiled preamble in `whatif`. + ## What it will not do - Profile macros. prumo stops at package, file, page and environment; `texprof` goes below that. - Change your build. The probe adds hooks and writes one record file; the PDF is - byte-identical with and without it, and that is a test. + byte-identical with and without it (see [How it works](#how-it-works) for the test). - Touch your files. Builds run on a copy; artifacts go to your cache directory (or whatever `--out` says), nothing next to your document. `prune --apply` is the one destructive command, it re-prints its plan first and needs `--yes`. diff --git a/docs/02-prior-art.md b/docs/02-prior-art.md index d803ba8..50c3825 100644 --- a/docs/02-prior-art.md +++ b/docs/02-prior-art.md @@ -1,9 +1,29 @@ # 02 — Prior art -Survey done 2026-11-06; the tools in A, B, C and E were installed and run on TeX Live 2026 on -2026-11-10 and the rows corrected. Verdict first: none of the six areas has a mature, maintained, -general-purpose tool. Two have narrow, usable prior art (dependency bundling; install-on-demand). -The rest have scripts, building blocks, or abandoned projects. +Survey done 2026-11-06. The tools in A, B, C and E were installed and run on TeX Live 2026 on +2026-11-10 and the rows corrected. SaTeX, DEPP, texdepend, texdeps, two TeX.SE questions and a +tex-live thread were added on 2026-11-12. SaTeX 0.2.2 and pdffonts were run that day; DEPP, +texdepend and texdeps were read but not run. Each gap below is what a +tool did on the date given, as a fact to design around, not a verdict on the tool. + +## Where prumo does the same thing + +- `unused`: remove the request, rebuild, compare the output. LaTeXpkges did it in 2015, and + latexpkges3 and stygtfo do it too (A). SaTeX's `unused-package` lint asks the same question + without a build. +- `graph`: a package dependency graph with Graphviz output, as latex-dependency-grapher draws + (C). +- `packages`: the files a run read (`-recorder`), mapped to TeX Live packages. mkjobtexmf + collects the same file list (E). Joseph Wright described the same `.fls`-to-package lookup + on the tex-live list in April 2024 and posted it as a script on TeX.SE (E, Demand signals). + DEPP builds its list from a `file/before` hook, as prumo's probe does (E). +- `prune`: a small install for a set of documents. TinyTeX and texliveonfly get there by + adding, mkjobtexmf by building a per-job tree, and DEPP by writing the list to install (E). +- `fonts`: the embedded side is pdffonts output (D). +- `time`: per-page timing with `\pdfelapsedtime` is a TeX.SE answer from 2014 (B). texprof + goes finer, to the line and the macro. +- `whatif`: a preamble precompiled with mylatexformat, draft mode and TikZ externalization are + existing techniques. prumo only measures them. ## By area @@ -11,79 +31,96 @@ The rest have scripts, building blocks, or abandoned projects. | Tool | Approach | Gap | |---|---|---| -| LaTeXpkges (bazzilic, 2015) / latexpkges3 (TarasKuzyo fork, PyPI 1.0, 2021) | Remove each top-level `\usepackage`, rebuild twice, compare an MD5 of the output (`.pdf`, `.xdv`, `.dvi`) with `/ID` stripped; `--visual` compares Ghostscript JPEGs | Top-level only (by its own README); the date patterns never match (missing commas in its pattern list), so timestamps trip the hash; `--visual` compares against a deleted directory and calls everything removable (checked 2026-11-10); writes trial files and deletes outputs in the document's directory | -| stygtfo (PyPI 0.1.0, 2022) | Comment out each column-0 `\usepackage` line, rebuild, compare pages with diff-pdf-visually | Tectonic only in practice (its README says so); with ImageMagick 7 identical pages compare as different; overwrites the input without `-o` | -| latex-dependency-grapher v1.0 (Java, CTAN 2024-01) | Regex scan of `\usepackage`/`\RequirePackage`/`\input`/`\include`, kpsewhich, GraphViz; "unused" = comment the line out, pdflatex still exits 0 | No output comparison; pdflatex only; the regex misses `\usepackage[opts]{x}`; no release since 1.0 | +| LaTeXpkges (bazzilic, 2015) / latexpkges3 (TarasKuzyo fork, PyPI 1.0, 2021) | Remove each top-level `\usepackage`, rebuild twice, compare an MD5 of the output (`.pdf`, `.xdv`, `.dvi`) with `/ID` stripped; `--visual` compares Ghostscript JPEGs | Top-level only, by its own README. Checked 2026-11-10: its date patterns never match (missing commas in the pattern list), so timestamps change the hash. `--visual` compares against a directory it has deleted and reports every package removable. It writes trial files and deletes outputs in the document's directory | +| stygtfo (PyPI 0.1.0, 2022) | Comment out each column-0 `\usepackage` line, rebuild, compare pages with diff-pdf-visually | Its README says it was tested with Tectonic only. Checked 2026-11-10: with ImageMagick 7, identical pages compare as different. Without `-o` it overwrites the input | +| latex-dependency-grapher v1.0 (Java, CTAN 2024-01) | Regex scan of `\usepackage`/`\RequirePackage`/`\input`/`\include`, kpsewhich, GraphViz; "unused" = comment the line out, pdflatex still exits 0 | No output comparison; pdflatex only. Checked 2026-11-10: the regex misses `\usepackage[opts]{x}`. No release since 1.0 | +| SaTeX 0.2.2 (Florian Sihler, Rust, 2026-11-12), `unused-package` lint | Static: an abstract interpretation of the document, no build. Fires when every name a loaded package defines is unused | A hint by its own description: side effects (layout, hooks, fonts, `\AtBeginDocument` code) are not seen. Run 2026-11-12 on prumo's basic fixture: no note for xcolor, which prumo's `unused` finds removable | | cmdtrack, refcheck, chklref, checkcites | Find unused *commands*, *labels*, *citations* | Not packages | | texlab, LaTeX Workshop, TeXstudio, LTeX | Editor diagnostics | No unused-package diagnostic | -**Reuse:** nothing to reuse; the idea of "remove and rebuild" is right, the execution is not. -prumo blocks packages at the kernel level (works for class-loaded packages too), seeds candidates -from probe data, and compares page text, not bytes. See `06-unused-packages.md`. +**Same idea:** prumo's `unused` is the remove-and-rebuild experiment LaTeXpkges ran in 2015, +and latexpkges3 and stygtfo run it too. The candidates come from the probe's records, so a +request in the user's own class or package counts as well. The request is deleted from its +loader's source, with blocking as the fallback. The comparison is page count, text and a +render, not bytes. See `06-unused-packages.md`. ### B. Compile-time profiling | Tool | Approach | Gap | |---|---|---| -| **texprof / texprofile** (Ruckert; TUGboat 45:2, 2024; in TeX Live's `hitex` package) | Its own engine (TeX + e-TeX + Prote, DVI output) records time per input line and per macro into `.tprof`; `texprofile` reports by file/line/macro with call-graph data; `-pdf` only stands in pdfTeX primitives when building a format | Not pdfTeX, XeTeX or LuaTeX; TeX Live 2026 ships no texprof formats, and a LaTeX format does not build against the 2026-11-01 kernel (macro stack overflow in expl3-code.tex); not package-oriented | +| **texprof / texprofile** (Ruckert; TUGboat 45:2, 2024; in TeX Live's `hitex` package) | Its own engine (TeX + e-TeX + Prote, DVI output) records time per input line and per macro into `.tprof`; `texprofile` reports by file/line/macro with call-graph data; `-pdf` only stands in pdfTeX primitives when building a format | Not pdfTeX, XeTeX or LuaTeX. TeX Live 2026 ships no texprof formats, and a LaTeX format does not build against the 2026-11-01 kernel (macro stack overflow in expl3-code.tex). Not package-oriented | +| TeX.SE 210139 (2014), Robert's answer 211572 | `\pdfelapsedtime` printed and `\pdfresettimer` called in `\AtBeginDocument` and `\AtBeginShipout`, one `timer:` line per page in the log; a 2020 answer (558409) does the same on LuaLaTeX with `os.clock()` | Added by hand, per page only. The answer itself notes that TeX's asynchronous output routine charges a page with material from the pages around it. `os.clock()` is CPU time, not wall clock | +| SaTeX 0.2.2, `--timings` | Per phase and per file, with token counts, for SaTeX's own interpretation of the document | Measures SaTeX's run, not the engine's ("Both measure the run itself", its README). Run 2026-11-12 on prumo's biblatex fixture: `biblatex.sty` 1,098 ms; the first run built a kernel cache from `latex.ltx` in 55 s | | l3benchmark (`\benchmark:n`, `tic`/`toc`) | expl3 timers you place by hand | Building block | | regstats, scrtime | Whole-run time | No breakdown | | ConTeXt `mtxrun --script profile` | Lua/TeX profiling | ConTeXt only | | latexmk | Build orchestration | No timing beyond `time latexmk` | -**Reuse:** `\sys_timer:` (expl3, all engines) — verified. Point users at texprof for per-macro -work; prumo is the engine-agnostic package/file/page layer above it. Ruckert's article notes that -no profiling tool had been available to macro package authors before texprof — that is the demand -signal. +**Same idea:** per-page timing is the TeX.SE answer's technique. prumo takes it from the +shipout hooks with `\sys_timer:` (expl3, all engines, verified) and adds packages, files and +phases. Point users at texprof for per-macro work; prumo is the engine-agnostic +package/file/page layer above it. Ruckert's article notes that no profiling tool had been +available to macro package authors before texprof, which is the demand signal. ### C. Package dependency graph | Tool | Approach | Gap | |---|---|---| -| latex-dependency-grapher | Regex scan of the source, kpsewhich resolution | Includes conditional loads that never happen (xcolor → colortbl); misses loads written with options or spaces, and class loads | +| latex-dependency-grapher | Regex scan of the source, kpsewhich resolution, Graphviz output | Checked 2026-11-10: includes conditional loads that never happen (xcolor → colortbl); misses loads written with options or spaces, and class loads | +| SaTeX 0.2.2, `--timings` | Prints the tree of files its interpretation read, which file under which | From the interpretation, not a build | | texfindpkg (Lyu, CTAN 2024A, in TeX Live and MiKTeX) | Which package provides a file, command or environment, its dependencies, and `tlmgr`/`miktex` install, from TeXstudio `.cwl` data and the tlpdb | Names in, not a document; the `.cwl` dependency data differs from what a build reads | | snapshot + bundledoc | `\listfiles`-style flat `.dep` list, then archive the files | Flat; no edges | +| texdepend (Friendly, Perl, 0.92), texdeps (Cozens); CTAN, not in TeX Live; not run | Scan the source for `\input`, `\include`, `\usepackage` and `\includegraphics` (texdeps optionally through kpsewhich) and print the files, for make or tar | Source scan; flat | | `\listfiles`, adhocfilelist, inputtrc | Flat lists / traces | No graph | | `-recorder` `.fls` | Every file read/written | Flat; no nesting | | texlogsieve (Lua, 1.6.1, 2026-01) | Rebuilds file nesting from the log's parentheses to filter messages | Does not export the tree; but its parser is the reference for log-based nesting | -**Reuse:** nothing directly; the `package/before` hook plus the depth counter gives exact edges -(verified). Use texlogsieve's approach as the cross-check parser for logs from runs without the -probe. +**Same idea:** latex-dependency-grapher draws the same kind of graph with Graphviz. prumo's +edges come from the `package/before` hook and a depth counter (verified), so they are the +loads that happened. Use texlogsieve's approach as the cross-check parser for logs from runs +without the probe. ### D. Font usage | Tool | Approach | Gap | |---|---|---| -| pdffonts (Poppler) | Lists fonts embedded in the PDF | Only the output side; Type 3 fonts are anonymous (`F44`) | +| pdffonts (Poppler; 26.07.0 run 2026-11-12) | Lists the fonts in the PDF: type, encoding, embedded, subset | Only the output side; Type 3 fonts are anonymous (`F44`) | | tracefnt / `\tracingfonts` | NFSS load/substitution trace in the log | Raw; no report | | pdfTeX log trailer | `<...pfb>` list of embedded Type 1 files | Hand parsing | -**Reuse:** pdffonts as the cross-check. The `.fls` is the better source on pdfTeX: `.tfm` INPUT = -loaded, `.pfb`/`.pk` INPUT = embedded (verified). Nothing links either to the package that caused -the load; prumo can, via the `.fd` file hook context. +**Same idea:** the embedded side of `fonts` is pdffonts output. The `.fls` is the better +source on pdfTeX: `.tfm` INPUT = loaded, `.pfb`/`.pk` INPUT = embedded (verified). Nothing +above links either to the package that caused the load; prumo does, through the `.fd` file +hook context. ### E. Slimming / pruning TeX Live | Tool | Approach | Gap | |---|---|---| | mkjobtexmf (Oberdiek, v0.8, 2011) | Run with `-recorder`/strace, symlink (or `--copy`) the used files into a job-local texmf tree | File level, one job, "experimental" by its own docs | +| DEPP 0.4 (Marei Peischl, Island of TeX, 2026-01-07; GitLab, not on CTAN; read, not run) | A package loaded before the document. A `file/before` hook guesses each file's TeX Live package from its path (`tex///`); `tlmgr search --file` through shell-escape for the rest; fonts through luaotfload, hyphenation patterns from babel or polyglossia. Writes `DEPENDS.txt` | Its documentation: works with LuaLaTeX, other engines in progress. Its README: the list is written at `\begin{document}`, so fonts loaded later are not in it yet. Lists what to install | +| `depreader.lua` (Joseph Wright, TeX.SE answer 716373, 2024-04-24) | Reads the `.fls`, runs `tlmgr search --file /` per file, prints the TeX Live packages and the files with no match | By its own list: only files a TeX run reads (not biber or makeindex), not format files, slow (one `tlmgr` call per file), no tlpdb `depend` edges | | snapshot + bundledoc (Pakin) | Archive a document's dependencies | For archiving, not for an install | | texliveonfly (2011) | Install missing packages via tlmgr while compiling | Add-only | | TinyTeX (Yihui Xie; the installer needs no R, the auto-install is in the R package) | Small TeX Live (about 100 packages by default) + auto-install missing packages from the log | Add-only | -| tlmgr | `scheme-minimal`, `scheme-infraonly`, `remove`, `search --global --file`, pinning, `--usermode` | No "remove what these documents don't use" | +| tlmgr | `scheme-minimal`, `scheme-infraonly`, `remove`, `search --global --file`, `search --json` (since 2024-04, after the thread below; works on TeX Live 2026), pinning, `--usermode` | No "remove what these documents don't use" | | Tectonic bundles | Self-contained bundles; custom bundles from a hand-written spec | No usage-driven subsetting | | MiKTeX | Install on the fly | No pruning | -**Reuse:** `texlive.tlpdb` as the file→package map (it is what `tlmgr search --file` reads). -Everything else only adds or copies. The inverse — subtract what the corpus doesn't use — is new. +**Same idea:** `packages` is the `.fls`-to-package lookup from the tex-live thread, and +mkjobtexmf collects the same file list. prumo reads `texlive.tlpdb` directly (it is what +`tlmgr search --file` reads), so it makes one read, not one `tlmgr` call per file. +`prune`'s `keep.txt` and `install-tl` profile serve the purpose DEPP's `DEPENDS.txt` does. The +tools above add packages, copy files or list what to install. None of them works out what an +installation can remove. ### F. General linters chktex, lacheck, nag, texlogsieve, texlogfilter, texfot, latexindent, TeXtidote, LTeX+, texcount, arara, rubber, latexmk, llmk, texlab: none covers A–E. `nag` warns about *obsolete* packages, which is adjacent and worth linking to in the unused report ("also: nag says this one is -obsolete"). +obsolete"). SaTeX (2026) lints a document by abstract interpretation and covers parts of A, +B and E (above). ## Kernel and distribution capabilities prumo stands on @@ -97,20 +134,46 @@ obsolete"). (XeTeX), and on LuaTeX to `os.gettimeofday()` minus an epoch that l3kernel sets to `gettimeofday() - os.clock()` when its Lua code loads (wall clock; finding 52). Unit: scaled seconds, 1/65536 s. +- **Poppler**: `pdffonts`, `pdftotext`, `pdftoppm`, `pdfinfo`. +- **latexmk** drives multi-pass builds; **mylatexformat** builds `whatif`'s precompiled + preamble. ## Demand signals -- TUGboat 45:2 (2024): texprof article — profiling demand from package authors. -- latex3/latex2e issue #1877 (Oct 2025): "LuaLaTeX is disproportionately slow" — engine - performance is an active topic; a per-package breakdown is the natural next question. +- TUGboat 45:2 (2024): texprof article, profiling demand from package authors. +- latex3/latex2e issue #1877 (Oct 2025): "LuaLaTeX is disproportionately slow". Engine + performance is an active topic, and a per-package breakdown is the natural next question. - LaTeX Workshop issue #2797: user asking which TeX Live packages are "absolutely necessary" because the default install is gigabytes of unneeded packages. +- TeX.SE 210139 (2014-11-02, "how to find bottleneck of long compiling time for my + document"): a 340-page document, and the asker wants "those 20% of the things which might + cause 80% of the compiling time". With the per-page timer, about 20 of the 340 pages took + more than half the time. +- TeX.SE 716306 (2024-04-23, "Automatically determine all ctan packages necessary to + compile") and the tex-live thread "tlmgr search output" that followed (2024-04-24, + messages 050431 to 050441). Joseph Wright started a script that uses `--recorder`, parses + the `.fls` and looks up the TeX Live package for each line. Marei Peischl replied that she + runs `tlmgr search --file` through shell-escape in a container, in a project on the Island + of TeX GitLab. DEPP is her project there, created in January 2024, and it does that. + Norbert Preining said he does this regularly, showed the output of + `tlmgr search --file /article.cls`, and added `tlmgr search --json` that day. Markus Kohm + pointed at texliveonfly. What came of it: Joseph's script as TeX.SE answer 716373, + `tlmgr search --json`, and DEPP, public on GitLab at 0.4. CTAN's package list has nothing + from the script as of 2026-11-12. ## Sources - https://github.com/bazzilic/LaTeXpkges · https://pypi.org/project/latexpkges3 - https://ctan.org/tex-archive/support/latex-dependency-grapher - https://tug.org/TUGboat/tb45-2/tb140ruckert-profiler.html +- https://github.com/EagleoutIce/satex-analyzer (SaTeX; github.com/gigalasr/satex-analyzer + is a fork from 2026-09-26 at 0.1.0) · https://crates.io/crates/satex-analyzer +- https://gitlab.com/islandoftex/texmf/depp +- https://tex.stackexchange.com/questions/210139 · https://tex.stackexchange.com/a/211572 +- https://tex.stackexchange.com/questions/716306 · https://tex.stackexchange.com/a/716373 +- https://tug.org/pipermail/tex-live/2024-April/050431.html (thread start) · + https://tug.org/pipermail/tex-live/2024-April/050436.html (Preining, `tlmgr search --file`) · + https://tug.org/pipermail/tex-live/2024-April/050440.html (`tlmgr search --json`) - https://ctan.org/pkg/texlogsieve - https://ctan.org/tex-archive/support/bundledoc · https://mirrors.mit.edu/CTAN/macros/latex/contrib/snapshot/snapshot.pdf - https://yihui.org/tinytex/ · https://github.com/cran/tinytex diff --git a/docs/06-unused-packages.md b/docs/06-unused-packages.md index 535f95c..09a1eb2 100644 --- a/docs/06-unused-packages.md +++ b/docs/06-unused-packages.md @@ -3,8 +3,16 @@ The question "can I delete this `\usepackage`?" cannot be answered by reading the source, because packages act by side effect (microtype, hyperref, babel, fontenc, geometry), by redefining existing commands (amsmath's `\boldsymbol`, `\eqref`), or by being loaded for a -single option. The honest answer is experimental: remove it, rebuild, see what changes. Prior -tools do that badly (top-level only, hash of PDF bytes). prumo does it properly. +single option. The answer has to come from an experiment: remove it, rebuild, see what +changes. + +Same idea as existing tools: LaTeXpkges did this in 2015, and latexpkges3 and stygtfo do it +too (`02-prior-art.md`, section A). SaTeX's `unused-package` lint asks the same question from +an abstract interpretation, without a build. In prumo the candidates come from the probe's +records, so a request in the user's own class or package counts as well, and the +comparison is page count, text and a render. LaTeXpkges looks only at the main file's top +level and compares an MD5 of the output; stygtfo compares rendered pages and was tested with +Tectonic only, by its README (both checked 2026-11-10). ## Candidates @@ -20,7 +28,7 @@ Skip list, reported as "loaded for side effects — not tested": `fontenc`, `inp `polyglossia`, `fontspec`, `microtype`, `geometry`, `hyperref`, `bookmark`, `lmodern` and other pure font-selection packages, `etoolbox`/`xparse`/`expl3` (kernel-adjacent), `nag`, `showframe`, `layout`, `lipsum`? (no — lipsum is testable). Keep the list short and editable -(`--test-all` overrides it). Hard-coding judgement is a smell; the list exists only because +(`--test-all` overrides it). Hard-coding judgment is a smell; the list exists only because these packages will always "pass" the no-change test while obviously doing something. ## Removing the request (the default since hardening 2) diff --git a/docs/08-open-questions.md b/docs/08-open-questions.md index 7f15e65..d7656a1 100644 --- a/docs/08-open-questions.md +++ b/docs/08-open-questions.md @@ -55,3 +55,22 @@ clearly marked placeholder. will reshape M4/M5. 12. **CTAN upload of the probe.** Yes/no, and whether to name it `prumo.sty` or something generic like `buildprobe.sty` so the CTAN package outlives the tool's name. + +## After launch: candidates from the prior-art review (2026-11-12) + +Recorded only. None of these is planned, and none has a default. + +13. **Per-pass and per-tool timing under latexmk:** pass 1, biber, pass 2, makeindex. Under + latexmk the record file is the last pass's, and there is no finalization phase. +14. **`prumo diff a.json b.json`**, and a budget or exit-code mode for CI. +15. **Opt-in command timing** on the generic `cmd//before` and `cmd//after` hooks. + The kernel implements those hooks by patching the command (`\__hook_patch_command:Nnn`, + ltcmdhooks), which conflicts with CLAUDE.md rules 3 and 5. A conflict to decide, not a + plan. +16. **`packages` on MiKTeX**, where texfindpkg maps names to packages and prumo reports files. + Also `packages` output as a `tlmgr install` line or a `DEPENDS.txt` (DEPP's file). +17. **Trace export:** speedscope or Chrome trace-event JSON. +18. **`unused --pairs`**, already mentioned in `06-unused-packages.md`: removing two packages + together when each one alone passes. + +On 12: texprof (in the `hitex` package) and texfindpkg both ship in TeX Live. diff --git a/docs/STATUS.md b/docs/STATUS.md index 80a4019..9899e63 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -1,140 +1,39 @@ # Status -## Launch prep (2026-11-09 and 10) - -This round adds a table of where a LaTeX run's time goes, from engine start to the closed -PDF, on each engine. Everything below was measured, and the method is in the repo so anyone -can check it. - -### Probe v0.2 - -- New records: `docstart` (end of `\begin{document}`), `lastpage` (after the final - `\clearpage`), and `env+`/`env-` for the environments named with - `\PrumoEnvironments{...}`. The CLI passes `--env` (default: tikzpicture, axis, tcolorbox, - tblr, longtable, tabularx, minted, lstlisting, forest; `none` for none). A command and not - a package option, because raw option handling changed since the 2021-06 floor. -- `docstart` and `end` go through `\AddToHookNext`, so they come after the code 92 TeX Live - files add to `begindocument/end` (amsmath among them) and after document-level code - (finding 53). -- A `ship` with no `page` is a discarded shipout. The model keeps it apart and the pages - section says so. -- Loaded from the main file's first line (Overleaf), the probe dropped its first event and - recorded its own `pkg-`. Both fixed (finding 56). -- PDF byte-identical with and without the probe on the seven fixtures and three engines, on - TeX Live 2026 and on Ubuntu 22.04's TeX Live 2021 (kernel 2021-11-15). New fixture - `environments` with seven claims, all tested. -- Oracle first: `prumo_report.py` has the phases, environments and discarded shipouts, the - goldens are regenerated, and the Rust matches on all 19 TeX Live 2026 sets. - `make_artifacts.sh` now sets `FORCE_SOURCE_DATE=1`; beamer's `\today` had changed a font - subset from one day to the next. - -### Phases, and how time is measured - -- `time` leads with the phase table (text, `--json` `phases`, `--html`): startup, preamble, - begin-document, typesetting, shipout, end-document, finalization. JSON adds `timer`, - `phases`, `environments` and `discarded_shipouts`; nothing was renamed. -- Finalization is the engine process's wall time minus the last record. `run.json` keeps - `wall_ns`, polled every millisecond (it was 20). Not measured under latexmk. -- The brief said LuaTeX's timer is `os.clock()`. It is not: l3kernel reads - `os.gettimeofday()` and uses `os.clock()` only to place the zero (finding 52). All three - timers are wall clock, and the README says how each is read. -- `compare` has a phases-by-engine table and ranks by wall time. The old total left out - startup and finalization and called LuaLaTeX fastest on a one-line document it was - slowest on (finding 55). With `--runs` 3 or more the median warm run is reported. - -### Benchmarks (`docs/benchmarks/`) - -- Ten documents now, three engines. Three live here (one line, the five-page paper, the - 3,991-page generated book). Seven are fetched at a pinned commit and never stored: the - ACM sigconf sample with BibTeX and with biblatex, the metropolis demo deck, florilegium's - manual, the HoTT book, Open Logic and the 7,710-page Stacks Project. `corpus.toml` has - each one's commit, license, engines and prepare step, `fetch.py` lays them out. kaobook - was left out, because thmtools' `sibling=` fails on the 2026-11-01 kernel, in five lines - too. -- `bench.py` has three modes: the phases (as before), `--overhead` (builds with and without - the probe in turns, plus per-package times from the probed records) and `--whatif`. - `charts.py` draws four SVG charts, light and dark, from the JSON. Color means phase in - all of them, and every pair of colors, the gray included, is checked with the dataviz - validator. -- The probe costs 7 ms on the one-line document and under 6% everywhere. On the paper, - LuaLaTeX's extra preamble time is biblatex (+151 ms) and fontspec's LuaTeX code (67 ms). -- On the corpus, the precompiled preamble works on two of the six pdfLaTeX - documents (paper 49%, deck 25%). Draft pays on XeLaTeX (13 to 38%). Externalize pays on - the deck and florilegium (15 to 32%), but its first run on a long book is a pass per - picture: 93 minutes on Open Logic for 4 s a build. -- The run had seven P-cores busy at once, and its phase numbers came out 0.3 to 5% slower - than the quieter run before it. The README says so. - -### Public documents - -ClassicThesis, the metropolis demo and the Llama 2 paper's arXiv source run through every -report command. kaobook's documentation fails on TeX Live 2026 with or without prumo. What -they changed: a failed build prints its first `!` error, plain output lists the slowest -`--top` pages instead of all of them, and the shipout hint names page and image writing, not -only hooks (finding 58). - -### Release check - -- v0.1.1 has its ten assets. `install.sh` from the README works in a clean Debian container, - `install.ps1` on the Windows box, `cargo install prumo` in `rust:1-slim`. -- `doctor` without LaTeX now says where to get it, folds the four Poppler rows into one that - says what is lost, and names MiKTeX when there is no tlpdb. -- v0.2.0 is released (2026-11-10, after the `whatif` PR). The release has its ten assets, - crates.io has 0.2.0, and ghcr has `0.2.0` and `0.2.0-small` for amd64 and arm64. The - one-line installer from the README installs 0.2.0 in a clean Debian container. - -### Related tools - -texprof, latexpkges3, latex-dependency-grapher, texfindpkg, stygtfo, TinyTeX, texliveonfly -and mkjobtexmf were each installed and run on TeX Live 2026. The README has a section on them -and a paragraph on texprof. texprof is not a pdfTeX: it is TeX with e-TeX and Prote, writes -DVI, and could not build a LaTeX format against the 2026-11-01 kernel. `docs/02-prior-art.md` -is corrected; CLAUDE.md still says "pdfTeX only". - -### whatif - -- `prumo whatif main.tex [--try preamble,draft,externalize] [--runs 5] [--shell-escape]`. - Each experiment rebuilds its own copy of the directory with one change. - The timed builds run without the probe: a warm-up each, then the baseline and the variants - in turns. Medians are compared. A difference no larger than the larger spread (2 ms at - least, the polling resolution) is "within noise". The output is compared by page count, - the words on each page and a 24 dpi render (finding 63). `--json` has the same fields - under schema 1. -- The builds run one at a time, not on `unused`'s parallel pool, because parallel builds - slow each other down. The temp copy, the timeout and the text comparison come from `run` - and `unused`. -- `preamble` works on pdfTeX (the fixture goes from 244 to 91 ms). XeTeX and LuaTeX fail, - and the row gives the error (finding 60). `doctor` has a mylatexformat row and the TeX - image installs it. -- `externalize`: turned on from the command line alone, the external library made every - picture build typeset the whole document (finding 61). The system call now carries the hook and names the engine. The text - is identical on all three engines, and ten pictures went from 944 to 138 ms. Without - `--shell-escape` it is refused when asked for and not run by default. The table and the - README mark it experimental. -- New fixture `whatif`, eight claims, all tested. `make_artifacts.sh whatif` regenerates one - fixture now. The fixture turned up finding 62: `doctor --check-log` now tells an - existence check from a read. -- Defaults: `--runs` is at least 2. The comparison uses the last run's PDF. Logs go to - `//whatif//`. With `--shell-escape` the probed run is - `--build " -shell-escape"`, so `time` rebuilds afterwards. No `--latexmk` or - `--build`, since their wall time is several passes. -- `cargo test`, clippy and fmt pass, and so do the 19 TeX tests in the image. TeX Live 2021 - runs it too (on a copy of the fixture without siunitx, which that image lacks). - -### Only if cheap - -- `prumo time output.prumo` and `prumo graph output.prumo` read records from a build prumo - did not run, and build nothing. `docs/overleaf.md` says how, from Overleaf's source; not - tried on overleaf.com. -- LuaLaTeX font definitions per page: the `luaotfload.patch_font` hypothesis is wrong for - `\addfontfeature`, so nothing shipped (finding 57). - -**Blocked:** nothing. -**Open questions:** should the LuaTeX font count go in after all, through `font.nextid()`? -Should `compare` default to three runs, so it reports a median? +## Prior art credited (2026-11-12) + +Docs only. Nothing in `src/`, `tex/`, `tests/` or `fixtures/` changed. Where prumo does what +an existing tool already does, the README and the design docs now say so by name, before +saying what differs. + +- README: Origin says most of the pieces exist elsewhere. Related tools has SaTeX, DEPP and + pdffonts, a "Same idea as existing tools" list and a "What differs" list. A new Built on + section credits the hooks, `\sys_timer:`, `-recorder`, the tlpdb, Poppler, latexmk and + mylatexformat. +- `docs/02-prior-art.md` has the same list, rows for SaTeX, DEPP, Joseph Wright's script, + texdepend, texdeps and the TeX.SE per-page timer, and the tex-live thread of April 2024 + under demand signals. Its gaps are dated facts now, without verdicts. + `06-unused-packages.md` got the same pass. +- SaTeX 0.2.2 and pdffonts 26.07.0 were run on TeX Live 2026. DEPP, texdepend and texdeps + were read, not run. +- The byte-identical test compares the whole PDF, built twice in one directory with + `SOURCE_DATE_EPOCH=0` and `FORCE_SOURCE_DATE=1`. The README says that now. The test passes + on the TeX Live 2026 image (2026-11-12). +- CLAUDE.md no longer calls texprof pdfTeX, and "Don't reinvent" names SaTeX, texfindpkg, + DEPP and mylatexformat. + +**Blocked:** nothing. DEPP is still to be run. +**Open questions:** 13 to 18 in `08-open-questions.md`, recorded from the review. CLAUDE.md +rule 3 allows more than the test checks ("modulo /CreationDate and ID"); should it say what +the test does? Carried over: should the LuaTeX font count go in through `font.nextid()`, and +should `compare` default to three runs? ## Earlier milestones, one line each +- **Launch prep, v0.2.0 (11-09 to 10):** probe v0.2 (`docstart`, `lastpage`, environments), + the phase table and wall-time finalization, `compare` by wall time, ten-document benchmarks + with probe overhead and `whatif`, the `whatif` command, Related tools, public documents, + v0.2.0 released. - **M6, polish and release (11-07 to 09):** `--html`, terminal charts, artifacts in the cache directory, `docker/prumo`, release images and binaries, the public repo at v0.1.0 then v0.1.1 (crate under trusted publishing), Windows verified on MiKTeX, one-line installers,