compile — cross-compiler LaTeX build

Quick path

latexmk -interaction=nonstopmode -halt-on-error -file-line-error -pdf <main>.tex

That's the answer for ~70% of documents. The rest need a different engine — detect first.

Engine detection

Run scripts/detect_compiler.sh <main>.tex. The script returns one of pdflatex, xelatex, lualatex. Decision precedence (deterministic):

1. Magic comment at top of file: % !TEX program = lualatex|xelatex|pdflatex → use it verbatim.
2. LuaLaTeX-only signal anywhere in source tree: \directlua, \luadirect, \usepackage{luacode}, \usepackage{luatexja} → lualatex.
3. XeLaTeX-only signal: \usepackage{xeCJK}, \usepackage{ctex} (default xetex mode), \usepackage{bidi} → xelatex.
4. Modern Unicode signal (engine-ambiguous): \usepackage{fontspec}, \usepackage{polyglossia}, \usepackage{luabidi}, \setmainfont, \setsansfont, \setmonofont, \newfontfamily, \newfontface → lualatex (preferred over xelatex for broader features and stronger RTL via luabidi).
5. Class signal: \documentclass{ctexart|ctexrep|ctexbook} (default xelatex) → xelatex.
6. Default: pdflatex (broadest journal-template compatibility, fastest).

Source: https://ctan.org/pkg/fontspec (fontspec aborts under pdftex). When uncertain on edge cases, delegate to /academic-latex:docs-lookup.

Run with the chosen engine

Source: latexmk manual at https://mirrors.ctan.org/support/latexmk/latexmk.pdf.

ENGINE=$(scripts/detect_compiler.sh "$MAIN")
case "$ENGINE" in
  pdflatex)  FLAG="-pdf"   ;;
  xelatex)   FLAG="-pdfxe" ;;
  lualatex)  FLAG="-pdflua";;
esac
latexmk $FLAG -interaction=nonstopmode -halt-on-error -file-line-error -synctex=1 "$MAIN"

Bibliography backend

latexmk auto-detects which to run:

• biblatex with backend=biber produces <main>.bcf — biber runs.
• natbib + \bibliography{} produces <main>.aux with \bibdata — bibtex runs.
• The $bibtex_use=2 default (run bib if requested) is correct for both. Don't override unless instructed.

Source: latexmk manual §$bibtex_use and §bib_dependencies.

When the document mixes (which is wrong — bibliography and biblatex together), report and stop; refer the user to /academic-latex:bibliography.

Multi-document workspace

If the user's directory has more than one .tex and no clear main:

1. Look for % !TEX root = <path> magic comments in the candidates.
2. Look for \documentclass{...} — files with that are entry points; files without are sub-includes.
3. Look for \begin{document} — must be present in the main.
4. If still ambiguous, ask the user (one question, list candidates).

On failure

If latexmk exit code is non-zero:

1. Capture the last 100 lines of the .log.
2. Invoke /academic-latex:debug with the path to <main>.log and <main>.tex. Do not attempt to fix in this skill — debug owns error classification and remediation.

The compile loop with debug:

compile → fail → debug → patch (with author or docs-lookup as needed) → compile

Stop after 3 unsuccessful iterations and surface the residual error to the user.

Cleanup

After a successful build, leave aux files in place — latexmk will use them on the next incremental build. To force a clean rebuild: latexmk -C (removes everything, including the PDF) or latexmk -c (keeps the PDF, removes intermediates).

When uncertain

Delegate package-specific or option-specific questions (e.g., "does this microtype option work under xelatex?") to /academic-latex:docs-lookup. Do not guess — see suite README.

Last verified

2026-05-09 — latexmk v4.88 (2026-03-09); fontspec docs at https://ctan.org/pkg/fontspec.