build-pmars

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

   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

   make clean  # If previous build artifacts exist
   make
   

2. Install to target location

   cp pmars /usr/local/bin/pmars
   # Or use: make install PREFIX=/usr/local
   

3. Verify no X11 dependencies

   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