How to Build a Release Binary for pdf‑inspector: A Complete Guide

Run cargo build --release in the firecrawl/pdf‑inspector repository to produce optimized, stripped binaries for pdf2md, detect‑pdf, and dump_ops in target/release/.

The pdf‑inspector crate from Firecrawl provides command‑line tools for PDF analysis and Markdown conversion. Building a release binary ensures you get maximum performance with optimizations enabled and debug symbols stripped—essential for distribution or production benchmarking. This guide walks through the complete build process based on the actual source structure in the firecrawl/pdf‑inspector repository.

Prerequisites: Rust Toolchain Setup

pdf‑inspector requires Rust 1.88 or later, as specified in [Cargo.toml](https://github.com/firecrawl/pdf-inspector/blob/main/Cargo.toml). Install or update your toolchain before building:

# Install rustup if needed

curl https://sh.rustup.rs -sSf | sh

# Use stable channel and update

rustup default stable
rustup update

Verify your version meets the requirement:

rustc --version

Understanding the Binary Structure

The crate defines three executables in [Cargo.toml](https://github.com/firecrawl/pdf-inspector/blob/main/Cargo.toml) under [[bin]] sections:

Binary	Source File	Purpose
pdf2md	[src/bin/pdf2md.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs)	Full PDF → Markdown conversion pipeline
detect-pdf	[src/bin/detect_pdf.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs)	Fast PDF type detection and metadata analysis
dump_ops	[src/bin/dump_ops.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/dump_ops.rs)	Low‑level PDF operator debugging utility

Each binary is a thin CLI wrapper around the core library defined in [src/lib.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs), which exposes functions like process_pdf, detect_pdf, and option builders.

Step‑by‑Step: Build Release Binary for pdf‑inspector

1. Clone the Repository

git clone https://github.com/firecrawl/pdf-inspector.git
cd pdf-inspector

2. Execute Release Build

Run Cargo with the --release flag to enable opt-level = 3 optimizations:

cargo build --release

The release profile compiles all three binaries with Link Time Optimization (LTO) and disables debug assertions for maximum speed.

3. Locate Output Binaries

After compilation completes, find your release binary for pdf‑inspector in target/release/:

ls -la target/release/

# pdf2md      (main extraction tool)

# detect-pdf  (fast detector)

# dump_ops    (debug utility)

4. Strip for Smaller Distribution

Reduce binary size by removing symbol tables:

strip target/release/pdf2md
strip target/release/detect-pdf
strip target/release/dump_ops

5. Verify Functionality

Confirm each release binary works correctly:

./target/release/pdf2md --help
./target/release/detect-pdf --help

Both should display usage information, available flags, and version details.

Using the Release Binaries

Convert PDF to Markdown

./target/release/pdf2md document.pdf > output.md

Detect PDF Type with JSON Output

./target/release/detect-pdf --json scanned-document.pdf

Debug PDF Operators

./target/release/dump_ops complex-layout.pdf

Core Library Architecture

The release binaries delegate work to well‑structured internal modules:

• Public API — [src/lib.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) defines process_pdf, process_pdf_with_options, and the PdfOptions builder pattern
• Type Detection — [src/detector.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs) handles PDF classification, tiled‑scan detection, and page sampling
• Extraction Pipeline — [src/extractor/mod.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/extractor/mod.rs) orchestrates text extraction with sub‑modules for content streams, fonts, and layout analysis
• Table Detection — src/tables/ contains three strategies: detect_rects.rs, detect_lines.rs, and detect_heuristic.rs
• Markdown Generation — [src/markdown/convert.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/markdown/convert.rs) implements the final conversion stage

Library Usage Example

For developers integrating pdf‑inspector into Rust applications rather than using CLI tools:

use pdf_inspector::{process_pdf_with_options, PdfOptions, ProcessMode};

fn main() -> Result<(), pdf_inspector::PdfError> {
    // Configure detection‑only mode for fast analysis
    let opts = PdfOptions::new()
        .mode(ProcessMode::DetectOnly);
    
    let result = process_pdf_with_options("document.pdf", opts)?;
    println!("Detected type: {:?}", result.pdf_type);
    Ok(())
}

This bypasses the CLI wrappers in [src/bin/pdf2md.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) and [src/bin/detect_pdf.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs) for direct library access.

Build Configuration Reference

Additional build options for specialized use cases:

# Build specific binary only

cargo build --release --bin pdf2md

# Build with specific features

cargo build --release --features parallel

# Cross-compilation example (requires appropriate target)

cargo build --release --target x86_64-unknown-linux-musl

Summary

• Primary command: cargo build --release produces optimized binaries in target/release/
• Three binaries: pdf2md, detect-pdf, and dump_ops defined in [Cargo.toml](https://github.com/firecrawl/pdf-inspector/blob/main/Cargo.toml)
• Minimum Rust version: 1.88 as declared in crate configuration
• Size optimization: Use strip on release binaries before distribution
• Source entry points: [src/bin/pdf2md.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) and [src/bin/detect_pdf.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs) wrap the [src/lib.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) public API

Frequently Asked Questions

What is the minimum Rust version required to build pdf‑inspector?

pdf‑inspector requires Rust 1.87 or later according to [Cargo.toml](https://github.com/firecrawl/pdf-inspector/blob/main/Cargo.toml). Run rustup update to ensure your toolchain meets this requirement before building.

How do I build only one binary instead of all three?

Use the --bin flag with Cargo: cargo build --release --bin pdf2md builds only the PDF‑to‑Markdown converter. This saves compilation time when you need just detect-pdf or dump_ops.

Where does the release profile configuration come from?

The release profile uses Cargo's default settings unless overridden: opt-level = 3 for optimizations, lto = false by default, and debug assertions disabled. pdf‑inspector does not define custom release profile overrides in its [Cargo.toml](https://github.com/firecrawl/pdf-inspector/blob/main/Cargo.toml).

Can I use pdf‑inspector as a library without building the binaries?

Yes. Add pdf_inspector = { git = "https://github.com/firecrawl/pdf-inspector" } to your Cargo.toml dependencies. Import from [src/lib.rs](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) using use pdf_inspector::{process_pdf, PdfOptions} and call functions directly without invoking the CLI wrappers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}