LTX

An extremely fast LaTeX project manager, written in Rust.

LTX scaffolds structured projects, lints your source, drives tectonic (and pdflatex/xelatex/lualatex), and gets out of your way — built for people who’d rather be writing than babysitting a build.

Status: pre-1.0. The CLI surface is stabilizing; expect minor breaking changes between minor versions until 1.0.

Why LTX?

Most LaTeX workflows are stitched together from shell scripts, latexmk, and muscle memory. LTX treats your document the way a modern build tool treats a codebase:

• Correct by construction — one ltx.toml describes your project; builds behave the same on your machine, your co-author’s machine, and in CI.
• Fast — a Rust core and a native engine mean large multi-file papers compile quickly, without a full TeX distribution installed.
• Predictable — the diagnostics pipeline gives you one consistent, source-spanning report for syntax and configuration problems.

Architecture

LTX is a Rust workspace composed of seven crates. Each crate owns its domain, and errors are defined in the crate that produces them — never centralized.

The pipeline

Source text flows through the toolchain in this order:

  .tex source
       │
       ▼
   LtxLexer          ──► TokenStream (LtxToken + LtxSpan)
       │
       ▼
   LtxParser          ──► AST (Document, Command, Environment, …)
       │
       ▼
   ParserErrorHandler ──► LtxDiagnosticSink (absorbs lexer + parser diagnostics)
       │
       ▼
   miette renderer    ──► Terminal output

1. Lexer scans raw bytes, applies TeX catcode rules, and emits LtxTokens with source spans. Problems are recorded by its own LexerErrorHandler.
2. Parser consumes the token stream via TokenStream (peek/bump/checkpoint/rewind), builds the AST, and reports through its own ParserErrorHandler, which absorbs the lexer’s diagnostics on construction.
3. Diagnostics accumulate in an LtxDiagnosticSink and render with miette for rich terminal output or serialize to JSON.

Error codes

Every diagnostic code is namespaced by the phase that owns it — 30 total:

Run ltx code to list them, filtered by phase (--lexer, --parser, --config, --compiler) or severity (-e, -w).

Quick start

# Scaffold a new project
ltx new my-paper
cd my-paper

# Check for errors
ltx check main.tex

# Build a PDF (tectonic is bundled; no TeX distribution needed)
ltx build

# List diagnostic codes
ltx code

Documentation pages

• Installation — prerequisites, cargo install, from-source
• CLI Usage — subcommands, flags, examples, exit codes
• Configuration — ltx.toml reference, scaffolding options
• API Overview — architecture + per-crate library reference
• Lexer Errors — LTX::LEXER::E0xx
• Parser Errors — LTX::PARSER::E0xx
• Config Errors — LTX::CONFIG::E0xx
• Compiler Errors — LTX::COMPILER::E0xx / W0xx

Installation

Prerequisites

• Rust 1.86+ — install via rustup

That’s it. LTX compiles with Tectonic, a self-contained, native-Rust TeX engine — no separate TeX distribution is required. The ltx build default uses tectonic and downloads its TeX Live bundle on first use.

Optional: if you’d rather use pdflatex, xelatex, or lualatex (or need a package not yet supported by Tectonic), install a traditional distribution and make sure its binaries are on your PATH:

• TeX Live (Linux, macOS, Windows)
• MiKTeX (Windows, macOS, Linux)
• MacTeX (macOS)

Install via Cargo

cargo install ltx

This downloads the latest published version from crates.io and compiles a release binary.

Install from source

git clone https://github.com/Abdogouhmad/ltx.git
cd ltx
cargo install --path .

This builds and installs the current main branch.

Verify installation

ltx --help
ltx --version
ltx code --lexer   # list the lexer diagnostic codes

You should see the CLI help text, the installed version, and the code table.

Platform notes

Linux

No special steps. If you use a traditional TeX distribution alongside Tectonic, ensure its binaries are on your PATH (TeX Live installs to /usr/local/texlive/… by default).

macOS

If you installed MacTeX, the binaries are at /Library/TeX/texbin/. Add this to your PATH if it isn’t already:

export PATH="/Library/TeX/texbin:$PATH"

Windows

MiKTeX or TeX Live should register themselves on the system PATH during installation.

Next steps

• CLI Usage — learn the available commands
• Configuration — set up ltx.toml for your project

CLI Usage

LTX provides five subcommands. Run ltx --help for the full reference.

ltx [COMMAND]

ltx new

Create a new LTX project with starter files.

ltx new <name> [OPTIONS]

Examples

# Flat layout (main.tex in project root)
ltx new my-paper

# With src/ directory
ltx new my-paper --src

# With bib/ directory and xelatex engine
ltx new my-paper --bib --engine xelatex

# Full layout: src/ + bib/ + tectonic
ltx new my-paper --src --bib --engine tectonic

Scaffolded layout

Without flags:

my-paper/
├── main.tex
├── references.bib
├── ltx.toml
└── .gitignore

With --src:

my-paper/
├── src/
│   ├── main.tex
│   └── sections/
├── references.bib
├── ltx.toml
└── .gitignore

With --bib:

my-paper/
├── main.tex
├── bib/
│   └── references.bib
├── ltx.toml
└── .gitignore

ltx check

Check a .tex file for syntax errors by running the full lex → parse → diagnostics pipeline.

ltx check <path>

Exit codes

Example

$ ltx check main.tex
Check passed — no issues found.

If errors are found, LTX renders them with source locations and help messages:

LTX::LEXER::E003

  × unmatched brace detected: `{`
   ╭─[main.tex:5:12]
 4 │ \section{Introduction
 5 │ % missing closing brace
   ·            ────┬────
   ·                ╰── here
 6 │
   ╰────
  help: Verify that every opening brace `{` has a matching closing brace `}`.

ltx build

Compile the project described in ltx.toml into a PDF.

ltx build

The manifest is validated first — missing keys, typos, and a missing main file fail fast with a source-spanning LTX::CONFIG::E0xx diagnostic. The selected engine then compiles the document:

• tectonic — compiled in-process by the tectonic crate (the default).
• pdflatex / xelatex / lualatex — not wired up yet; a LTX::COMPILER::W001 warning is printed and the build exits successfully.

Output is always written to the project’s target/ directory.

ltx clean

Remove the target/ directory and print a summary of deleted files and total size, akin to cargo clean.

ltx clean

ltx code

List all registered diagnostic error codes with their descriptions, severities, and owning phase.

ltx code [FILTER]

Output:

CODE                     DESCRIPTION                                SEVERITY  PHASE
--------------------------------------------------------------------------------
LTX::LEXER::E001         Unexpected Token                           error     lexer
LTX::LEXER::E002         Unexpected End of File                     error     lexer
LTX::LEXER::E003         Unmatched Brace                            error     lexer
...
LTX::COMPILER::W001      Engine Not Implemented                     warning   compiler

30 total codes

Global flags

Engine options

LTX supports four LaTeX compilers, set via ltx new --engine or in the [build] section of ltx.toml:

Next steps

• Configuration — customize your project with ltx.toml
• Lexer Errors — the LTX::LEXER::E0xx code table

Configuration

Every LTX project is described by an ltx.toml at its root. The ltx new command generates this file automatically. Only two sections exist: [project] for metadata and [build] for compilation settings.

Full reference

[project]
name = "my-paper"          # Required. Project name.
version = "0.1.0"          # Optional. Semver version string.
author = ["Author Name"]   # Optional. List of authors.
main = "src/main.tex"      # Required (validation). Path to the main .tex file.

[build]
name = "my-paper"          # Required (validation). Output PDF name, no extension.
engine = "tectonic"        # Required. pdflatex | xelatex | lualatex | tectonic
engine_args = ["-synctex=1"]   # Optional. Extra compiler arguments.

[build.options]            # Optional. Tectonic compilation options.
keep_logs = true           # Optional. Keep the .log file.   Default: true
keep_intermediates = false # Optional. Keep .aux/.synctex.gz. Default: false
synctex = true             # Optional. Emit SyncTeX data.     Default: true
only_cached = false        # Optional. Never hit the network. Default: false

The compiled PDF is always written to the project’s target/ directory — there is no output-directory option.

Sections

[project]

* main is optional in the data model but required by validation — ltx build and ltx check refuse to run without it. See LTX::CONFIG::E001 in the Config Errors table.

[build]

* name is required by validation (LTX::CONFIG::E003).

[build.options]

Tectonic compilation options. Every field defaults to a sensible value when omitted, so a project only sets the options it wants to override.

Validation rules

ltx build validates the manifest before compiling. Malformed TOML and unknown keys (e.g. a typo like [build.option]) are rejected loudly instead of silently ignored. The structural rules enforced by validate_manifest():

1. [project].main is set and points to an existing file on disk (LTX::CONFIG::E001, LTX::CONFIG::E004).
2. A [build] section is present (LTX::CONFIG::E002).
3. [build].name is non-empty (LTX::CONFIG::E003).

Scaffolding options

When you run ltx new, the directory layout is controlled by flags that map to internal options:

SrcLayout — source file placement

BibLayout — bibliography placement

These flags combine freely. For example, ltx new paper --src --bib creates:

paper/
├── src/
│   ├── main.tex
│   └── sections/
├── bib/
│   └── references.bib
├── ltx.toml
└── .gitignore

Minimal config

A project with just the essentials (generated by ltx new my-paper):

[project]
name = "my-paper"
main = "main.tex"

[build]
name = "my-paper"
engine = "tectonic"

Example: bibliography project

[project]
name = "thesis"
version = "0.1.0"
author = ["Jane Doe <jane@example.com>"]
main = "src/main.tex"

[build]
name = "thesis"
engine = "tectonic"

[build.options]
keep_logs = false
only_cached = true

Related

• CLI Usage — the build / check / code commands
• Config Errors — the LTX::CONFIG::E0xx code table

API Overview

Reference for the LTX library crates, for Rust consumers embedding LTX as a library. The workspace is seven crates; each owns its domain and its errors. Errors flow through the shared ltx_diagnostics infrastructure to render, but are defined in the crate that produces them.

Crate map

Dependency direction

Dependencies point inward toward reusable infrastructure. ltx_diagnostics never depends on the other crates, so the graph stays acyclic:

ltx_utils ──► ltx_config ──► ltx_compiler ──► ltx_cli
                    │              │
                    ▼              ▼
ltx_lexer ──► ltx_parser ──► ltx_diagnostics (shared rendering)

The diagnostic pipeline

Any error type implements LtxDiagnosticSource and is wrapped in an LtxDiagnostic together with the LtxSourceMap needed to render it. Diagnostics accumulate in an LtxDiagnosticSink, then render with miette or serialize to JSON — the diagnostics crate never needs to know which phase produced an error.

Lexer ──► LexerError ──┐
                       ├─► LtxDiagnostic ──► LtxDiagnosticSink ──► miette renderer
Parser ──► ParserError ┘                                  └─────► JSON

Code registry

Each crate exports a pub const ALL_CODES: &[ErrorCode] table. The CLI aggregates all of them for ltx code:

See the Error codes section for full tables.

ltx_diagnostics

Pure diagnostic infrastructure for the LTX toolchain. This crate defines no domain errors — it only provides the building blocks other crates plug into to report, render, and serialize diagnostics.

Responsibilities

• source file management (LtxSourceMap, LtxSourceFile)
• byte-range span utilities (LtxSpan, LtxFileId)
• severity classification (LtxSeverity: Error / Warning / Hint)
• miette integration and rendering
• batch diagnostic reporting (LtxDiagnosticSink)
• the LtxDiagnosticSource helper trait that every crate’s error enum implements
• the ErrorCode registry metadata struct

Key types

Error ownership

Domain errors live in the crates that produce them, not here:

Each of those crates exports a pub const ALL_CODES: &[ErrorCode] registry that the CLI aggregates for ltx code.

Rendering

• render_pretty(diagnostic) / render_pretty_into(...) — miette graphical output
• render_json_into(sink, writer) — JSON-serializable diagnostics for tooling

Usage

#![allow(unused)]
fn main() {
use ltx_diagnostics::{LtxSourceMap, LtxDiagnosticSink, LtxDiagnostic, LtxDiagnosticSource};

let mut source_map = LtxSourceMap::new();
let file_id = source_map.add_file("main.tex")?;
// ... produce an error implementing LtxDiagnosticSource ...
let diagnostic = LtxDiagnostic::new(error, source_map.into());
}

Design constraints (see AGENT.md)

• Never define domain errors here.
• Never depend on lexer / parser / config / compiler crates (keeps the graph acyclic).

ltx_lexer

Byte-level tokenizer for LaTeX source files. Converts raw .tex text into a stream of LtxTokens, each carrying an LtxTokenKind, an LtxSpan, and the source slice it was parsed from. Mode-aware (Normal / Math) with catcode state tracking per the TeX specification.

Responsibilities

• lexical analysis and token generation
• category code handling (LtxCatCode, LtxCatCodeState)
• lexer-specific diagnostics (owned by this crate)

Key types

Error ownership

LexerError (in src/error.rs) owns every lexer diagnostic: unexpected token, unexpected EOF, unmatched brace, invalid math delimiter, unterminated argument, invalid escape sequence, invalid unicode, illegal parameter char, unterminated verbatim, invalid character, and mismatched environment. Codes are registered in ALL_CODES under the LTX::LEXER::E0xx namespace. See the Lexer Errors table.

Usage

#![allow(unused)]
fn main() {
use ltx_lexer::{LtxLexer, TokenStream};
use ltx_diagnostics::LtxSourceMap;

let mut source_map = LtxSourceMap::new();
let file_id = source_map.add_file("main.tex")?;
let stream = TokenStream::new(LtxLexer::new(source, file_id, source_map.into()));

// Hand the stream to the parser, or drive LtxLexer directly.
}

Design notes

• Zero string allocations for tokens — tokens borrow from the source text.
• Most consumers create a TokenStream and pass it to ltx_parser; only streaming consumers need LtxLexer directly.

ltx_parser

Recursive-descent parser for LaTeX. Consumes a ltx_lexer::TokenStream and produces an AST.

Responsibilities

• syntax parsing and AST generation
• parser-specific diagnostics (owned by this crate)

Architecture

• parser::LtxParser wraps a TokenStream and exposes cursor methods (peek, bump, checkpoint/rewind, skip_ws).
• parser_traits::Parse is the trait every AST node implements.
• ast contains the node types: Document, Command, Environment, Math, Group, Text, Comment, UsePackage, DocumentClassDecl, Arg, …
• parse_document is the top-level convenience entry point.

AST nodes

Error ownership

ParserError (in src/error.rs) owns all 6 parser diagnostics (LTX::PARSER::E001–E006):

ParserErrorHandler collects these. When LtxParser::new is constructed it drains the lexer’s diagnostics into the same handler, so a single sink reports both phases. See the Parser Errors table.

Usage

#![allow(unused)]
fn main() {
use ltx_parser::{LtxParser, parse_document};

let mut parser = LtxParser::new(stream);
let doc = parse_document(&mut parser);

let handler = parser.error_handler_mut();
if handler.has_errors() {
    eprintln!("{}", handler.render_pretty());
}
}

Design notes

• Zero token clones: AST nodes store Range<usize> token spans or zero-copy &'src str slices.
• Diagnostics flow through ltx_diagnostics for rendering — the parser owns the errors, the diagnostics crate renders them.

ltx_config

Configuration and project scaffolding. Provides the data model for ltx.toml, manifest validation, and project generation.

Responsibilities

• manifest parsing (LtxManifest)
• configuration validation (validate_manifest)
• project scaffolding (scaffold)
• config-specific diagnostics (owned by this crate)

Key types

Error ownership

ConfigError (in src/error.rs) owns every manifest/scaffold diagnostic, including the merged former ManifestDiagnostic + ScaffoldError:

Validation errors embed the raw source text and a byte span so they render with miette snippets pointing at the offending table or key. See the Config Errors table.

Usage

#![allow(unused)]
fn main() {
use ltx_config::{LtxManifest, Project, Build, CompilerEngine, scaffold, ScaffoldOptions};

// Read + validate in one step
let manifest = LtxManifest::from_file("ltx.toml")?;

// Scaffold a new project
scaffold(&project_dir, &ScaffoldOptions::new("my-paper", CompilerEngine::Tectonic))?;
}

Design notes

• Unknown keys in ltx.toml are rejected loudly (serde deny_unknown_fields) instead of silently ignored.
• No dependency on lexer/parser — the config layer only talks to ltx_diagnostics (for ErrorCode) and ltx_utils (filesystem helpers).

ltx_compiler

Compilation orchestration. Turns a validated manifest into a compiled PDF by dispatching to a configured engine. Currently only the tectonic engine is wired up; the other engines emit a warning.

Responsibilities

• compilation pipeline (build)
• engine abstraction (CompilerConfig, engine dispatch)
• tectonic integration (tectonic_compile)
• file watching for rebuild-on-save (watch)
• compiler-specific diagnostics (owned by this crate)

Key types

Error ownership

CompilerError (in src/error.rs):

CompilerError implements miette::Diagnostic so it converts into miette::Report and can be returned directly from miette::Result functions. See the Compiler Errors table.

Engine behavior

• tectonic — real compilation via the tectonic crate.
• pdflatex / xelatex / lualatex — emit LTX::COMPILER::W001 through miette to stderr and return Ok(()) (a warning never fails the build).

Usage

#![allow(unused)]
fn main() {
use ltx_compiler::{CompilerConfig, build};

let manifest = ltx_config::LtxManifest::from_file("ltx.toml")?;
let config = CompilerConfig::from_manifest(&manifest)?;
build::build(&config, project_root)?;
}

Design notes

• Input is a CompilerConfig; output always goes to target/.
• watch.rs watches only the src/ root (structured ltx new --src projects) or the main file itself (single-structure ltx new projects), plus the manifest, and rebuilds through build::build on every relevant change (.tex, .sty, .cls, .bib). The compiler’s own target/ output is never watched, so builds cannot feed back into a rebuild loop. Driven by the ltx watch CLI command.

ltx_utils

Low-level filesystem helpers. Small, dependency-free utilities shared by the other crates for common I/O operations.

Functions

Usage

#![allow(unused)]
fn main() {
use ltx_utils::{create_dir, write_file};

create_dir(Path::new("my-paper/src/sections"))?;
write_file(Path::new("my-paper/main.tex"), r"\documentclass{article}")?;
}

Design notes

• No dependencies on other ltx_* crates — usable from anywhere in the workspace.
• All functions return std::io::Result; no panicking variants.

Lexer Errors (LTX::LEXER::E001-E011)

The lexer transforms source text into a token stream during the initial compilation phase. This section enumerates all lexer-related errors, their causes, and recommended resolutions.

Error Reference Table

Error Categories

Syntax Errors (LTX::LEXER::E001-E006)

These errors occur when the input violates lexical grammar rules.

LTX::LEXER::E001 - UnexpectedToken
The lexer encountered a sequence that does not form a valid token in the current state. Check for:

• Special characters in invalid contexts
• Malformed commands or arguments
• Syntax that does not conform to the language specification

LTX::LEXER::E002 - UnexpectedEOF
The source input terminated prematurely. Verify that:

• All environment blocks are closed
• Every opening brace has a matching closure
• Command argument lists are complete

LTX::LEXER::E003 - UnmatchedBrace
Brace matching failed during tokenization. Inspect:

• Brace pair count (each { requires a })
• Brace nesting order
• Arguments enclosed within braces

LTX::LEXER::E004 - InvalidMathDelimiter
Math mode delimiters are incorrectly specified. Valid delimiters:

• Inline: $...$ or \(...\)
• Display: $$...$$ or \[...\]

LTX::LEXER::E005 - UnterminatedArgument
A command argument lacks its closing brace. Each { that starts an argument must have a matching }.

LTX::LEXER::E006 - InvalidEscapeSequence
The sequence following a backslash does not form a valid command. Ensure the command name consists of valid characters and exists in the context.

Encoding and Character Errors (LTX::LEXER::E007-E010)

These errors relate to character encoding and invalid character handling.

LTX::LEXER::E007 - InvalidUnicode
The source file contains bytes that do not form valid UTF-8 sequences. Re-encode the file using UTF-8.

LTX::LEXER::E008 - IllegalParameterChar
The # character is used in an invalid context. Proper usage:

• Macro parameter references: #1, #2, etc.
• Macro definitions only

LTX::LEXER::E009 - UnterminatedVerbatim
A verbatim environment was opened but not closed. Ensure the verbatim block terminates correctly.

LTX::LEXER::E010 - InvalidCharacter
The lexer encountered a character not permitted in the current context. Remove or replace the offending character.

Environment Errors (LTX::LEXER::E011)

LTX::LEXER::E011 - MismatchedEnvironment
An \end{...} names a different environment than the one opened by the matching \begin{...}, or an \end appears with no corresponding \begin. Every environment must be closed with the same name it was opened with.

Diagnostic Example

🔍 Found 1 issue(s):

LTX::LEXER::E001

  × unexpected token `@`
   ╭─[main.tex:3:19]
 2 │ % E001: Unexpected Token
 3 │ \newcommand{\foo} @invalid
   ·                   ────┬───
   ·                       ╰── here
 4 │
   ╰────
  help: Check for invalid characters, malformed commands, or unsupported syntax near the highlighted position.

Related Topics

• ltx_lexer API — the crate that owns these errors
• Parser Errors — errors produced during AST construction

Parser Errors (LTX::PARSER::E001-E006)

The parser analyzes the token stream produced by the lexer and constructs an Abstract Syntax Tree (AST) according to the language grammar. This section lists all parser-related errors, their causes, and recommended fixes.

Error Reference Table

Error Categories

Token Errors (LTX::PARSER::E001-E002)

LTX::PARSER::E001 - ExpectedToken

The parser expected a specific token — such as {, }, or an environment — but found something else or reached the end of the stream.

% ❌ Incorrect (missing closing brace)
\newcommand{\foo}{Hello

% ✅ Correct
\newcommand{\foo}{Hello}

LTX::PARSER::E002 - UnexpectedEOF

A construct being parsed (for example inline math) ran to the end of the file without its closing delimiter.

% ❌ Incorrect
A sentence with $x + y = z$

% ✅ Correct
A sentence with $x + y = z$.

Environment Errors (LTX::PARSER::E003-E004)

LTX::PARSER::E003 - UnclosedEnvironment

An environment was opened with \begin{...} but never closed with \end{...}.

% ❌ Incorrect
\begin{itemize}
\item First item
\item Second item

% ✅ Correct
\begin{itemize}
\item First item
\item Second item
\end{itemize}

LTX::PARSER::E004 - MismatchedEnvironment

The environment closing tag doesn’t match the opening tag.

% ❌ Incorrect
\begin{itemize}
\item First item
\end{enumerate}

% ✅ Correct
\begin{itemize}
\item First item
\end{itemize}

Group Errors (LTX::PARSER::E005)

LTX::PARSER::E005 - MissingClosingBrace

A braced group { ... reached the end of the token stream without a matching }.

% ❌ Incorrect
\section{Introduction

% ✅ Correct
\section{Introduction}

Document Structure Errors (LTX::PARSER::E006)

LTX::PARSER::E006 - UnexpectedEOFWhileParsing

The top-level document parsing ended before a required structure — such as \begin{document} — was found.

% ❌ Incorrect
\documentclass{article}
Hello world

% ✅ Correct
\documentclass{article}
\begin{document}
Hello world
\end{document}

Diagnostic Example

🔍 Found 1 issue(s):

LTX::PARSER::E004

  × mismatched environment: expected `\end{itemize}`, found `\end{enumerate}`
    ╭─[main.tex:18:1]
 17 │ \begin{itemize}
 18 │ \end{enumerate}
    · ────────┬───────
    ·         ╰── here
 19 │
    ╰────
  help: Environments must be closed with the same name they were opened with.

Best Practices

1. Always use matching \begin and \end pairs - Keep environments properly nested
2. Verify command spelling - Use autocompletion or reference documentation
3. Load required packages - Ensure all necessary packages are imported
4. Close every brace and argument - Each { needs a matching }
5. Structure the document correctly - Include \begin{document} after the preamble

Related Topics

• ltx_parser API — the crate that owns these errors
• Lexer Errors - Errors during tokenization
• Config Errors - Manifest validation errors

Config Errors (LTX::CONFIG::E001-E008)

The config crate owns every error it can produce while reading or validating ltx.toml and while scaffolding a new project. Manifest-validation errors embed the raw source text and a byte span so they render with a miette snippet pointing at the offending table or key; read failures and scaffold I/O errors have no source snippet.

Error Reference Table

Validation rules

validate_manifest() (called by ltx build and LtxManifest::from_file()) rejects a manifest when:

1. [project].main is missing (E001) or points to a file that does not exist (E004).
2. The [build] section is absent (E002).
3. [build].name is missing (E003).

Malformed TOML and unknown keys (e.g. a typo like [build.option]) are reported as E005 before any semantic checks run.

Diagnostic Example

LTX::CONFIG::E001

  × missing `main` in the `[project]` section
   ╭─[ltx.toml:1:1]
 1 │ [project]
   · ────┬────
   ·     ╰── the `main` key is required here
 2 │ name = "demo"
   ╰────
  help: add `main = "src/main.tex"` (or the path to your main file)

Related Topics

• Configuration — the ltx.toml reference
• Compiler Errors — errors produced during compilation

Compiler Errors (LTX::COMPILER::E001-E004, W001)

The compiler crate owns every error it can produce while turning a manifest into a compiled PDF: missing configuration, missing input files, and engine (tectonic) failures. CompilerError implements miette::Diagnostic, so it converts into a miette::Report and is returned directly from miette::Result functions.

Error Reference Table

Error Categories

Configuration Errors (E001-E002)

These mirror the config-layer validation but occur at compile time, when the resolved CompilerConfig is missing information it needs.

E001 - MissingMain
The [project] section has no main entry, so the compiler doesn’t know which file to compile.

E002 - MissingBuild
The manifest has no [build] section, so the engine and output name are unknown.

Input Errors (E003)

E003 - MainFileNotFound
The main input file resolved from [project].main does not exist on disk at build time. Note the config layer catches this earlier during validation (LTX::CONFIG::E004); this variant covers paths resolved at compile time.

Engine Errors (E004)

E004 - TectonicError
The selected engine failed to fetch its support bundle, create its processing session, or finish the compilation. The message carries the underlying engine error.

Warnings (W001)

W001 - EngineNotImplemented
The selected engine is not wired up yet — only tectonic is available. The warning is rendered through miette and the build still exits successfully.

Diagnostic Example

LTX::COMPILER::W001

  ⚠ `pdflatex` engine is not implemented yet — only `tectonic` is available
  help: use `engine = "tectonic"` in `ltx.toml`, or wait for this engine to
        land

Related Topics

• Configuration — engine selection in ltx.toml
• Config Errors — manifest validation errors