Building from Source

This guide covers building printwell from source.

Prerequisites

Rust 1.92+ (with rustup)
Docker (for building Chromium)
Node.js 18+ (for Node.js bindings)
Python 3.9+ (for Python bindings)
~100GB disk space (Chromium source)

Quick Build

# Clone repository
git clone https://github.com/printwell-dev/core
cd printwell

# Initialize (downloads Chromium, applies patches)
cargo xtask init

# Build native library
cargo xtask build

# Build CLI
cargo build --release -p printwell-cli

Build Steps Explained

1. Initialize

cargo xtask init

This command:

Creates the chromium/ directory
Runs fetch chromium via depot_tools
Applies patches from patches/
Sets up GN build files

2. Build Native Library

cargo xtask build

This command:

Runs inside Docker for reproducibility
Compiles Chromium’s Blink, Skia, and PDFium
Produces libprintwell_native.so (~50MB)

Build options:

# Debug build (faster, larger)
cargo xtask build --debug

# Release build (optimized)
cargo xtask build --release

# Specify CPU cores
cargo xtask build --jobs 8

3. Build Rust Crates

cargo build --release

4. Build Language Bindings

# Node.js binding
cargo xtask bindings node

# Python binding
cargo xtask bindings python

# Both
cargo xtask bindings all

Docker Build Environment

The build uses Docker to ensure reproducibility:

FROM debian:bookworm-slim

# Build tools
RUN apt-get update && apt-get install -y \
    build-essential \
    clang \
    lld \
    ninja-build \
    python3 \
    git \
    curl

GN Configuration

Build settings in docker/gn_args/common.gn:

# Disable features we don't need
blink_enable_javascript = false
enable_pdf = false
enable_extensions = false
media_use_ffmpeg = false

# Use headless rendering
use_ozone = true
ozone_platform_headless = true

Updating Chromium

# Update to latest
cd chromium/src
git fetch
git checkout <new-version>
gclient sync

# Re-apply patches
cd ../..
cargo xtask chromium patch

Troubleshooting

Build Fails with Memory Error

Reduce parallelism:

cargo xtask build --jobs 4

Missing depot_tools

git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
export PATH="$PATH:$(pwd)/depot_tools"

Docker Permission Denied

sudo usermod -aG docker $USER
# Log out and back in

Development Workflow

# Run tests
cargo xtask test

# Run lints
cargo xtask lint

# Run benchmarks
cargo xtask bench

# Run e2e tests
cargo xtask e2e

Keyboard shortcuts

printwell