Skip to content

CLAUDE.md

Latest commit

 

History

History
206 lines (162 loc) · 5.81 KB

CLAUDE.md

File metadata and controls

206 lines (162 loc) · 5.81 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

FluffOS is an LPMUD driver based on the last release of MudOS (v22.2b14) with 10+ years of bug fixes and performance enhancements. It supports all LPC-based MUDs with minimal code changes and includes modern features like UTF-8 support, TLS, WebSocket protocol, async IO, and database integration.

Architecture

Core Components

Driver Layer (src/)

  • main.cc - Entry point for the driver executable
  • backend.cc - Main game loop and event handling
  • comm.cc - Network communication layer
  • user.cc - User/session management
  • symbol.cc - Symbol table management
  • ofile.cc - Object file handling

VM Layer (src/vm/)

  • vm.cc - Virtual machine initialization and management
  • interpret.cc - LPC bytecode interpreter
  • simulate.cc - Simulation engine for object lifecycle
  • master.cc - Master object management
  • simul_efun.cc - Simulated external functions

Compiler Layer (src/compiler/)

  • compiler.cc - LPC-to-bytecode compiler
  • grammar.y - Grammar definition (Bison)
  • lex.cc - Lexical analyzer
  • generate.cc - Code generation

Packages (src/packages/)

  • Modular functionality organized by feature (async, db, crypto, etc.)
  • Each package has .spec files defining available functions
  • Core packages: core, crypto, db, math, parser, sockets, etc.

Networking (src/net/)

  • telnet.cc - Telnet protocol implementation
  • websocket.cc - WebSocket support for web clients
  • tls.cc - SSL/TLS encryption support
  • msp.cc - MUD Sound Protocol support

Build System

CMake Configuration (CMakeLists.txt, src/CMakeLists.txt)

  • CMake 3.22+ required
  • C++17 and C11 standards
  • Jemalloc for memory management (recommended)
  • ICU for UTF-8 support
  • OpenSSL for crypto features

Build Options (key flags)

  • MARCH_NATIVE=ON (default) - Optimize for current CPU
  • STATIC=ON/OFF - Static vs dynamic linking
  • USE_JEMALLOC=ON - Use jemalloc memory allocator
  • PACKAGE_* - Enable/disable specific packages
  • ENABLE_SANITIZER=ON - Enable address sanitizer for debugging

Build Commands

Development Build

# Standard development build
mkdir build && cd build
cmake ..
make -j$(nproc) install

# Debug build with sanitizer
cmake .. -DCMAKE_BUILD_TYPE=Debug -DENABLE_SANITIZER=ON

Production Build

# Production-ready static build
cmake .. -DCMAKE_BUILD_TYPE=Release -DSTATIC=ON -DMARCH_NATIVE=OFF
make install

Package-Specific Builds

# Build without database support
cmake .. -DPACKAGE_DB=OFF

# Build with specific packages disabled
cmake .. -DPACKAGE_CRYPTO=OFF -DPACKAGE_COMPRESS=OFF

Testing

Unit Tests

# Run all tests (requires GTest)
cd build
make test

# Run specific test executable
./src/lpc_tests
./src/ofile_tests

LPC Tests

# Run LPC test suite
cd testsuite
../build/bin/driver config.test

Integration Testing

# Run driver with test configuration
./build/bin/driver testsuite/etc/config.test

Development Workflow

Code Generation

Several source files are auto-generated during build:

  • grammar.autogen.cc/.h - From grammar.y (Bison)
  • efuns.autogen.cc/.h - From package specifications
  • applies_table.autogen.cc/.h - From applies definitions
  • options.autogen.h - From configuration options

Adding New Functions

  1. Add function to appropriate package .spec file
  2. Implement function in corresponding .cc file
  3. Run build to regenerate autogenerated files
  4. Add tests in testsuite/ directory

Debugging

# Build with debug symbols and sanitizer
cmake .. -DCMAKE_BUILD_TYPE=Debug -DENABLE_SANITIZER=ON

# Run with GDB
gdb --args ./build/bin/driver config.test

# Memory debugging with Valgrind
valgrind --leak-check=full ./build/bin/driver config.test

Platform-Specific Notes

Ubuntu/Debian

# Install dependencies
sudo apt install build-essential bison libmysqlclient-dev libpcre3-dev \
  libpq-dev libsqlite3-dev libssl-dev libz-dev libjemalloc-dev libicu-dev

macOS

# Install dependencies
brew install cmake pkg-config mysql pcre libgcrypt libevent openssl jemalloc icu4c

# Build with environment variables
OPENSSL_ROOT_DIR="/usr/local/opt/openssl" ICU_ROOT="/usr/local/opt/icu4c" cmake ..

Windows (MSYS2)

# Install MSYS2 packages
pacman -S git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake
pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-libevent \
  mingw-w64-x86_64-pcre mingw-w64-x86_64-icu mingw-w64-x86_64-openssl

# Build in MINGW64 terminal
cmake -G "MSYS Makefiles" ..

Key Directories

  • src/ - Main driver source code
  • src/packages/ - Modular package implementations
  • src/vm/ - Virtual machine and interpreter
  • src/compiler/ - LPC compiler
  • src/net/ - Network protocol implementations
  • testsuite/ - LPC test programs and configurations
  • docs/ - Documentation (Markdown and Jekyll)
  • build/ - Build output directory (auto-generated)

Configuration Files

  • Config.example - Example driver configuration
  • src/local_options - Local build options (copy from local_options.README)
  • testsuite/etc/config.test - Test configuration
  • Package-specific .spec files define available functions

Common Development Tasks

Adding a New Package

  1. Create directory in src/packages/[package-name]/
  2. Add CMakeLists.txt, .spec file, and source files
  3. Update src/packages/CMakeLists.txt
  4. Add tests in testsuite/

Modifying Compiler

  1. Edit src/compiler/grammar.y for syntax changes
  2. Regenerate grammar with Bison if available
  3. Update corresponding compiler components

Debugging Memory Issues

  1. Build with -DENABLE_SANITIZER=ON
  2. Use mud_status() efun in LPC for runtime memory info
  3. Check testsuite/log/debug.log for detailed logs