rgoue/BUILD_ISSUES.md

Build Issues Found During README Testing

This document lists issues encountered when following the README.md build instructions on macOS (darwin 25.0.0, Apple Silicon).

Date

Testing performed: Following README.md Quick Start instructions

Environment

• OS: macOS (darwin 25.0.0)
• Architecture: Apple Silicon (arm64)
• Compiler: GCC/Clang (available)
• make: Available
• ncurses: Installed via Homebrew at /opt/homebrew/opt/ncurses

Issues Found

1. Compilation Error: Incomplete Type 'WINDOW'

Location: main.c:241-242

Error Message:

main.c:241:11: error: incomplete definition of type 'WINDOW' (aka 'struct _win_st')
  241 |     curscr->_cury = oy;
      |     ~~~~~~^
main.c:242:11: error: incomplete definition of type 'WINDOW' (aka 'struct _win_st')
  242 |     curscr->_curx = ox;
      |     ~~~~~~^

Root Cause: The code attempts to access internal ncurses structure members (curscr->_cury and curscr->_curx) which are not part of the public API in modern ncurses libraries. These internal members are not accessible in both the system ncurses and Homebrew ncurses.

Context: The problematic code is in the tstp() function (lines 241-242), which handles stop/start signals (SIGTSTP). After resuming from a stop signal, the code tries to manually restore the cursor position by directly accessing internal ncurses structure members.

Affected Code:

void
tstp(int ignored)
{
    // ... code ...
    getyx(curscr, y, x);
    mvcur(y, x, oy, ox);
    fflush(stdout);
    curscr->_cury = oy;  // ERROR: Internal member access
    curscr->_curx = ox;  // ERROR: Internal member access
}

Impact:

• Severity: CRITICAL - Build fails completely
• The game cannot be compiled on modern systems with standard ncurses
• This affects all platforms using modern ncurses (not just macOS)

Suggested Fix:

1. Remove the direct structure member access (lines 241-242)
2. The mvcur() call on line 239 should be sufficient for cursor positioning
3. If cursor position tracking is needed, use public ncurses API functions like getyx() and move() instead

Workaround Attempted:

• Tried using Homebrew ncurses with explicit include/library paths as suggested in README troubleshooting section
• Same error occurred with both system ncurses and Homebrew ncurses
• Tried manual build using Makefile.std as documented in README (Alternative build method)
• Same error occurred with manual build method
• This confirms it's a code compatibility issue, not a configuration or build system issue

2. Compiler Warnings (Non-blocking)

Location: Multiple files

Warning Messages:

• main.c: Multiple warnings about deprecated function prototypes (C23 compatibility)
• Function declarations without prototypes in extern.h conflicting with definitions

Impact:

• Severity: LOW - Warnings only, do not prevent compilation
• Code compiles but may have issues with future C standards (C23)

Note: These warnings are expected for legacy C code and don't prevent the build from succeeding once the critical error is fixed.

What Works

1. ✅ Configure script: Runs successfully

   • Detects compiler, headers, and libraries correctly
   • Creates config.h and Makefile properly
   • Works with both system ncurses and Homebrew ncurses paths

2. ✅ Prerequisites: All required tools are available

   • C compiler (gcc/clang)
   • make
   • ncurses library (via Homebrew)

3. ✅ Build system: Autotools configuration works correctly

   • configure script exists and is executable
   • No need for autoreconf (as documented in README)

Recommendations for README Updates

1. Add Known Compatibility Issue Section:

   • Document that the codebase has compatibility issues with modern ncurses
   • Note that direct access to internal ncurses structures (curscr->_cury, curscr->_curx) will fail on modern systems
   • Provide information about which ncurses versions are known to work (if any)

2. Update macOS Troubleshooting:

   • The current macOS troubleshooting section mentions Homebrew ncurses paths, but this doesn't solve the compilation error
   • Add a note that even with correct ncurses paths, the build may fail due to code compatibility issues

3. Add Build Status:

   • Consider adding a "Known Issues" or "Build Status" section to the README
   • Indicate that the codebase may need patches for modern ncurses compatibility

Next Steps

1. Code Fix Required: The main.c file needs to be updated to remove direct access to internal ncurses structure members
2. Testing: After fix, verify the game builds and runs correctly
3. Documentation: Update README with any workarounds or fixes applied

Additional Notes

• The README's Quick Start instructions are clear and easy to follow
• The build system (Autotools) is properly configured
• The issue is specifically with code compatibility, not with the build system or documentation
• This appears to be a known issue with porting old curses-based code to modern ncurses