Unified Build System User Guide

The Codexis Unified Build System provides efficient multi-format book building through a shared temporary directory architecture. This eliminates redundant LaTeX processing and significantly improves build performance.

Overview

What is the Unified Build System?

The Unified Build System coordinates all format builds (PDF, HTML, EPUB, DOCX, etc.) through a single shared temporary directory. Instead of each format creating its own temporary workspace and reprocessing LaTeX from scratch, the system:

1. Processes LaTeX once during the PDF build, generating all auxiliary files
2. Shares auxiliary files (.aux, .toc, .bbl, .tdo) across all format builders
3. Builds formats concurrently after PDF completion
4. Manages cleanup centrally with configurable policies

Key Benefits

• Performance: 40-60% faster builds for multi-format outputs
• Efficiency: Reduced disk I/O and memory usage
• Consistency: All formats use identical auxiliary files
• Reliability: Comprehensive error handling and recovery
• Debugging: Optional temp directory preservation for troubleshooting

Basic Usage

Building All Formats (Recommended)

# Build all supported formats using unified system
./codexis build --all --source manuscript --output output

This command:

• Creates a shared temporary directory
• Builds PDF first (generating auxiliary files)
• Builds other formats concurrently using shared auxiliary files
• Copies all outputs to the specified output directory
• Cleans up temporary files

Building Specific Formats

# Single format (still uses unified system for consistency)
./codexis build --format pdf --source manuscript --output output

# Multiple specific formats
./codexis build --format pdf,html,epub --source manuscript --output output

Build Process Flow

graph TD
    A[./codexis build --all] --> B[Create BuildOrchestrator]
    B --> C[Setup shared temp directory]
    C --> D[Copy source files once]
    D --> E[Build PDF first]
    E --> F[Generate auxiliary files]
    F --> G[Build other formats in parallel]
    G --> H[Copy outputs to destination]
    H --> I[Cleanup temp directory]

Advanced Usage

Debugging Builds

When builds fail, you can preserve the temporary directory for investigation:

# Show temp directory path and preserve it after build
./codexis build --all --show-temp-dir --preserve-temp-dir --source manuscript --output output

This will output something like:

Temporary directory: /tmp/codexis_build_1748057072_abc123de
Building PDF...
Building HTML...
Build completed. Temporary directory preserved for debugging.

You can then examine the temporary directory structure:

ls -la /tmp/codexis_build_1748057072_abc123de/
# source/     - Source files
# aux/        - LaTeX auxiliary files  
# output/     - Format outputs
# logs/       - Build logs

Custom Temporary Directory Location

For CI environments or when /tmp has limited space:

# Use custom temp directory root
./codexis build --all --temp-dir-root /custom/temp/path --source manuscript --output output

Build Options

The unified build system supports all standard build options:

# With custom options
./codexis build --all \
  --source manuscript \
  --output output \
  --clean \
  --table-of-contents \
  --preserve-temp-dir \
  --show-temp-dir

Temporary Directory Structure

The BuildOrchestrator creates a standardized directory hierarchy:

/tmp/codexis_build_<timestamp>_<random>/
├── source/manuscript_source/    # Source files copied here
│   ├── manuscript.tex
│   ├── content/
│   │   ├── chapters/
│   │   ├── front-matter/
│   │   └── back-matter/
│   ├── images/
│   ├── styles/
│   └── meta.yaml
├── aux/                        # LaTeX auxiliary files (shared)
│   ├── manuscript.aux          # Citations and references
│   ├── manuscript.toc          # Table of contents
│   ├── manuscript.bbl          # Bibliography
│   ├── manuscript.tdo          # Todo list
│   ├── manuscript.lot          # List of tables
│   ├── manuscript.lof          # List of figures
│   └── ...
├── output/                     # Format-specific outputs
│   ├── pdf/
│   │   └── manuscript.pdf
│   ├── html/
│   │   ├── manuscript.html
│   │   └── manuscript.css
│   ├── epub/
│   │   └── manuscript.epub
│   ├── docx/
│   │   └── manuscript.docx
│   └── markdown/
│       └── manuscript.md
├── assets/                     # Processed assets
├── images/                     # Image processing workspace
├── styles/                     # Style files
└── logs/                       # Build logs per format
    ├── pdf_build.log
    ├── html_build.log
    └── ...

Configuration

Environment Configuration

You can configure the unified build system through your config files:

# config/config.exs
config :codexis, :build_orchestrator,
  temp_dir_root: System.tmp_dir!(),
  cleanup_on_success: true,
  preserve_on_error: true,
  secure_permissions: true,
  concurrent_builds: true

CLI Flag Reference

Troubleshooting

Common Issues

Build fails with "Permission denied"

# Check temp directory permissions
ls -la /tmp/codexis_build_*
# Should show drwx------ (700 permissions)

"Directory already exists" error

# Clean up stale temp directories
rm -rf /tmp/codexis_build_*

Out of disk space in /tmp

# Use custom temp location with more space
./codexis build --all --temp-dir-root /var/tmp --source manuscript --output output

Debugging Failed Builds

1. Preserve the temp directory:

   ./codexis build --all --preserve-temp-dir --show-temp-dir --source manuscript --output output
   

2. Check build logs:

   # Navigate to temp directory (shown in output)
   cd /tmp/codexis_build_1748057072_abc123de
   
   # Check format-specific logs
   cat logs/pdf_build.log
   cat logs/html_build.log
   

3. Examine auxiliary files:

   # Check if LaTeX auxiliary files were generated
   ls -la aux/
   
   # Look for LaTeX errors
   cat aux/manuscript.log
   

4. Verify source files:

   # Ensure source files were copied correctly
   ls -la source/
   diff -r source/ ../original/manuscript/
   

Performance Tips

1. Use SSD storage for temp directories when possible
2. Increase available temp space for large documents
3. Monitor memory usage during concurrent builds
4. Use --preserve-temp-dir only for debugging (increases disk usage)

Migration from Legacy Build System

Backward Compatibility

The unified build system is fully backward compatible:

• Existing CLI commands work unchanged
• Same output quality and formatting
• All configuration options preserved
• No changes needed to manuscript files

Performance Comparison

Migrating Custom Scripts

If you have custom scripts that call Codexis builds:

Before (still works):

./codexis build --format pdf --source manuscript --output output
./codexis build --format html --source manuscript --output output  
./codexis build --format epub --source manuscript --output output

After (recommended):

./codexis build --all --source manuscript --output output

Best Practices

For Development

• Use --preserve-temp-dir when debugging build issues
• Use --show-temp-dir to understand temp directory location
• Build all formats together with --all for consistency testing

For CI/CD

• Specify --temp-dir-root if /tmp has limited space
• Use --clean to ensure clean builds
• Avoid --preserve-temp-dir in CI to prevent disk space issues

For Large Documents

• Monitor available disk space in temp directory location
• Consider using faster storage (SSD) for temp directories
• Use custom temp directory root on high-performance storage

API Reference

BuildOrchestrator Module

defmodule Codexis.BuildManager.BuildOrchestrator do
  @doc "Create a new build orchestrator with shared temp directory"
  def create(source_dir, opts \\ [])

  @doc "Get path to source directory in temp workspace"
  def source_dir(orchestrator)

  @doc "Get path to auxiliary files directory"
  def aux_dir(orchestrator)

  @doc "Get path to output directory"
  def output_dir(orchestrator)

  @doc "Clean up temp directory based on policy"
  def cleanup(orchestrator)

  @doc "List all orchestrator-managed temporary build directories with metadata"
  def list_temp_dirs(opts \\ [])
end

BuildManager Integration

defmodule Codexis.BuildManager do
  @doc "Build formats using unified system"
  def build(source_dir, output_dir, options \\ %{})
end

For more detailed API documentation, see the module documentation in the source code.