---
name: build-pov-ray
description: Guidance for building POV-Ray (Persistence of Vision Raytracer) from source, particularly legacy versions like 2.2. This skill should be used when tasked with downloading, compiling, and installing POV-Ray from source archives. It covers handling legacy C code, compressed archive formats, build system navigation, and verification strategies for successful compilation.
---

# Build POV-Ray

## Overview

This skill provides guidance for building POV-Ray from source code, with particular focus on legacy versions (e.g., POV-Ray 2.2 from the early 1990s). Building legacy software requires persistence, direct execution approaches, and systematic verification at each step.

## Critical Success Factors

Building legacy software requires:

1. **Persistence through obstacles** - Old code often needs patches or workarounds
2. **Direct execution** - Shell commands are more reliable than web browsing for downloads
3. **Verification at each step** - Ensures exact knowledge of where failures occur
4. **Knowledge of build systems** - Understanding Makefiles, configure scripts, and compiler flags
5. **Completion focus** - Partial work produces no usable output; continue until success or clear blocking error

## Workflow

### Step 1: Verify Build Prerequisites

Before attempting to download or compile, verify available build tools:

```bash
# Check for essential build tools
which gcc make
gcc --version
make --version

# Check for additional tools that may be needed
which wget curl tar uncompress gzip
```

Common prerequisites for POV-Ray:
- GCC (C compiler)
- make (build automation)
- X11 development libraries (for display support, if needed)
- Math libraries (usually included with libc)

### Step 2: Locate and Download Source Archives

**Prefer direct download commands over web browsing.** Known archive locations for POV-Ray:

- Official FTP: `ftp://ftp.povray.org/pub/povray/`
- Archive mirrors may include: `*.tar.Z`, `*.tar.gz`, `*.zip` formats

Direct download approach:

```bash
# Create working directory
mkdir -p /app/povray-2.2
cd /app/povray-2.2

# Download using wget or curl (example URLs - verify actual locations)
wget ftp://ftp.povray.org/pub/povray/Old-Versions/POV-Ray-2.2/povray22.tar.Z

# Alternative: use curl
curl -O <archive-url>
```

**Verification:** After download, confirm file exists and has reasonable size:

```bash
ls -la povray*.tar*
file povray*.tar*
```

### Step 3: Extract Source Archives

Handle different compression formats:

```bash
# For .tar.Z files (compress format from 1990s)
uncompress povray22.tar.Z && tar xvf povray22.tar
# Or combined:
zcat povray22.tar.Z | tar xvf -

# For .tar.gz files
tar xzf povray22.tar.gz

# For .zip files
unzip povray22.zip
```

**Verification:** Confirm extraction produced source files:

```bash
ls -la
find . -name "*.c" | head -5
find . -name "Makefile*" | head -5
```

### Step 4: Examine Build System

Before compiling, understand the build structure:

```bash
# Look for build instructions
cat README* INSTALL* 2>/dev/null | head -100

# Find makefiles
find . -name "Makefile*" -o -name "makefile*"

# Check for configure script
ls -la configure* 2>/dev/null

# Examine makefile targets
head -50 Makefile
grep -E "^[a-zA-Z_-]+:" Makefile | head -20
```

Legacy POV-Ray versions typically use plain Makefiles without autoconf/automake.

### Step 5: Configure and Compile

For legacy POV-Ray (2.x series):

```bash
# Navigate to Unix source directory (common structure)
cd unix/  # or src/ or source/

# Review and potentially edit Makefile for your system
# May need to adjust:
# - CC (compiler)
# - CFLAGS (compiler flags)
# - LDFLAGS (linker flags)
# - Install paths

# Compile
make

# If errors occur, try with specific flags
make CFLAGS="-O2 -w"  # -w suppresses warnings from old code
```

**Common compilation issues with legacy code:**

1. **Implicit function declarations** - Add appropriate `#include` headers or use `-w` flag
2. **Missing prototypes** - Legacy C code may predate ANSI C
3. **Library linking errors** - Add `-lm` for math library
4. **Path issues** - Verify header file locations

### Step 6: Install Binary

```bash
# Install to standard location
sudo cp povray /usr/local/bin/
sudo chmod +x /usr/local/bin/povray

# Or install via makefile if target exists
sudo make install
```

**Verification:**

```bash
# Confirm binary exists and is executable
ls -la /usr/local/bin/povray
file /usr/local/bin/povray

# Test execution
/usr/local/bin/povray --help 2>&1 | head -20
# Or for older versions that may not have --help:
/usr/local/bin/povray 2>&1 | head -20
```

### Step 7: Functional Verification

Test with a simple scene file:

```bash
# Create minimal test scene
cat > test.pov << 'EOF'
camera { location <0, 2, -3> look_at <0, 1, 2> }
sphere { <0, 1, 2>, 2 texture { pigment { color rgb <1, 0, 0> } } }
light_source { <2, 4, -3> color rgb <1, 1, 1> }
EOF

# Render test scene
/usr/local/bin/povray test.pov +W320 +H240 +Otest.tga

# Verify output was created
ls -la test.tga
file test.tga
```

## Common Pitfalls

### Pitfall: Incomplete Execution

**Problem:** Stopping mid-process without completing the build cycle.

**Prevention:** Continue execution until either:
- The binary is successfully installed and verified
- A clear, documented blocking error prevents progress

### Pitfall: Over-reliance on Web Browsing

**Problem:** Using web search and page fetching when direct downloads would be faster and more reliable.

**Prevention:** For known software with established archive locations, use `wget` or `curl` directly. Web browsing should only be used when archive URLs are genuinely unknown.

### Pitfall: Missing Verification Steps

**Problem:** Proceeding without confirming each step succeeded.

**Prevention:** After each major action, verify:
- Downloads: File exists with reasonable size
- Extraction: Source files present
- Compilation: Binary produced without errors
- Installation: Binary in target location and executable
- Function: Binary runs and produces expected output

### Pitfall: Ignoring Build Prerequisites

**Problem:** Attempting compilation without verifying required tools exist.

**Prevention:** Always check for `gcc`, `make`, and other dependencies before starting the build process.

### Pitfall: Not Reading Documentation

**Problem:** Attempting to build without checking README or INSTALL files.

**Prevention:** Legacy software often has specific build instructions. Read available documentation before modifying Makefiles or running make.

## Verification Checklist

Use this checklist to confirm successful completion:

- [ ] Source archive downloaded (verify file exists and size > 0)
- [ ] Archive extracted (verify `.c` files present)
- [ ] Build documentation reviewed
- [ ] Compilation completed without errors
- [ ] Binary exists at target location (`/usr/local/bin/povray`)
- [ ] Binary is executable (`file` command shows executable)
- [ ] Binary runs and accepts input
- [ ] Test render produces output file