---
name: build-pmars
description: Guidance for building pMARS (portable Memory Array Redcode Simulator) from source. This skill should be used when tasked with compiling pMARS, building Core War simulators from source packages, or creating headless/non-X11 builds of legacy C software from Debian source packages.
---

# Build pMARS

## Overview

This skill provides guidance for building pMARS (portable Memory Array Redcode Simulator) from Debian source packages, specifically for creating headless builds without X11 dependencies. The approaches and verification strategies apply broadly to building legacy C software from source packages.

## Recommended Approach

### Phase 1: Preparation and Documentation Review

Before modifying any build configurations:

1. **Review available documentation first**
   - Read Makefile comments to understand available build options
   - Check README files for build instructions and configuration flags
   - Review debian/control for Build-Depends to understand required dependencies

2. **Check build dependencies early**
   - Run `apt-get build-dep <package>` to install all build dependencies
   - Alternatively, review debian/control file and install Build-Depends manually
   - Install `dpkg-dev` package if working with Debian source packages

3. **Enable source repositories**
   - For DEB822 format (modern Ubuntu/Debian): Edit `/etc/apt/sources.list.d/*.sources` and ensure `Types:` line includes `deb-src`
   - For traditional format: Uncomment or add `deb-src` lines in `/etc/apt/sources.list`
   - Run `apt-get update` after modifying source lists

### Phase 2: Source Acquisition

1. **Download source package**
   ```bash
   apt-get source pmars
   ```

2. **Extract to target location**
   - Move or extract source files to the required build directory (e.g., `/app`)

### Phase 3: Build Configuration for Headless Mode

To build pMARS without X11 support:

1. **Modify CFLAGS in Makefile**
   - Remove `-DXWINGRAPHX` from CFLAGS to disable X11 graphics
   - Remove `-DCURSESGRAPHX` if curses support is also unwanted

2. **Remove X11 library linkage**
   - Remove `-lX11` and any X11-related libraries from LDFLAGS/LIBS
   - Remove `-lcurses` or `-lncurses` if disabling curses support

3. **Verify Makefile changes**
   - After editing, read the Makefile to confirm changes are correct
   - Check for any conditional build logic that might override changes

### Phase 4: Compilation and Installation

1. **Compile the source**
   ```bash
   make clean  # If previous build artifacts exist
   make
   ```

2. **Install to target location**
   ```bash
   cp pmars /usr/local/bin/pmars
   # Or use: make install PREFIX=/usr/local
   ```

3. **Verify no X11 dependencies**
   ```bash
   ldd /usr/local/bin/pmars
   ```
   - Output should NOT contain libX11, libXt, or other X11 libraries

## Verification Strategies

### Binary Verification

- Use `ldd` to verify linked libraries match expectations
- Run the binary with `--help` or without arguments to confirm basic functionality
- Check binary location and permissions

### Functional Testing

- Test with actual warrior files to verify core functionality
- When testing flags like `-f` (fixed position), understand the flag behavior from help text or source before testing
- Create a simple test script for repeated testing rather than running similar commands multiple times

### Debugging Approach

When encountering crashes or segmentation faults:

1. **Install debugging tools**: `apt-get install gdb`
2. **Compile with debug symbols**: Add `-g` to CFLAGS and rebuild
3. **Run under GDB** to get precise stack traces before applying fixes
4. **Investigate environmental differences** if behavior differs between GDB and direct execution
5. **Avoid speculative fixes** - understand the root cause before modifying source code

## Common Pitfalls

### Configuration Errors

- **DEB822 format confusion**: Modern Debian/Ubuntu use `.sources` files with YAML-like format, not the traditional one-line format
- **Missing dpkg-dev**: Source package operations require `dpkg-dev` package
- **Incomplete dependency installation**: Always check Build-Depends before compiling

### Build Process Mistakes

- **Editing wrong Makefile section**: Some Makefiles have multiple configuration sections; ensure edits target the correct section
- **Incomplete X11 removal**: Both CFLAGS defines AND library linkage must be modified for headless builds
- **Not cleaning before rebuild**: After Makefile changes, run `make clean` before `make`

### Testing Mistakes

- **Misunderstanding flag behavior**: Read help text or source to understand flag semantics before testing
- **Running repetitive similar commands**: Create a test script instead of manually running variations
- **Insufficient verification**: A single test passing does not guarantee full functionality

### Debugging Mistakes

- **Applying speculative fixes**: Always confirm hypothesis with debugging data before modifying source
- **Ignoring environmental differences**: Different behavior under GDB vs direct execution indicates environmental issues
- **Not verifying edits**: After editing configuration files, always read them back to confirm correctness

## Decision Tree

```
Is the task to build pMARS from source?
├── Yes → Continue with this skill
│   ├── Need headless/non-X11 build?
│   │   ├── Yes → Remove XWINGRAPHX from CFLAGS, remove -lX11 from libs
│   │   └── No → Use default Makefile settings
│   ├── Encountering build errors?
│   │   ├── Missing dependencies → Run apt-get build-dep or install manually
│   │   ├── Source not found → Enable deb-src repositories
│   │   └── Compilation errors → Check Makefile edits for typos
│   └── Encountering runtime errors?
│       ├── Segfault → Use GDB with debug symbols to diagnose
│       ├── Missing libraries → Check ldd output, install required libs
│       └── Unexpected behavior → Read source/help to understand expected behavior
└── No → This skill may not apply
```