Skip to content

CLAUDE.md

Latest commit

 

History

History
92 lines (69 loc) · 5.07 KB

CLAUDE.md

File metadata and controls

92 lines (69 loc) · 5.07 KB
Raw

Claude Code Session Context for miniscrip2

Project Overview

This is MiniScript 2.0 - a dual-language (C#/C++) VM implementation using a transpiler-based architecture. Always start by reading README.md and the various .md documents in the notes folder for comprehensive project details.

Key Architecture:

  • C# source code in cs/ directory (primary development language)
  • Transpiler converts C# → C++ (output in generated/)
  • C/C++ core runtime in cpp/core/ (memory management, Value types, etc.)
  • Build system orchestrated by tools/build.sh

Key Technical Implementations

1. Computed-Goto Dispatch System

Location: cpp/core/dispatch_macros.h, plus generated C++ VM code

  • Uses X-macro pattern to automatically generate VM_LABEL_LIST from opcode enum
  • Supports both computed-goto (GNU C extension) and switch-based dispatch
  • Build system allows forcing dispatch method: tools/build.sh cpp {auto|on|off}
  • Performance benefit: Direct jumps vs. switch statement overhead

2. Function Call/Return Mechanism

Key insight: Uses function indices instead of copying FuncDef objects for efficiency

  • CallInfo struct: stores ReturnPC, ReturnBase, ReturnFuncIndex
  • CALLF_iA_iBC: saves caller context, switches to callee function by index
  • RETURN: restores caller function using functions[callInfo.ReturnFuncIndex]
  • VM state: tracks currentFuncIndex and FuncDef& curFunc (C++ uses reference to avoid copying)

3. Build System & Performance

Main command: tools/build.sh {setup|cs|transpile|cpp|all|clean|test}

  • Computed-goto control: tools/build.sh cpp {auto|on|off}
  • Auto-detection: Uses GNU C extensions test, requires -std=gnu++11 (not -std=c++11)
  • Optimization: C++ builds with -O3 -DNDEBUG for production performance
  • Benchmark suite: tools/benchmark.sh for performance comparison

Important Files to Know

Core Implementation

  • cs/App.cs - Main host application
  • cs/VM.cs - Main VM implementation (C# source)
  • generated/VM.g.cpp - Transpiled VM (auto-generated from C#)
  • cpp/core/dispatch_macros.h - Computed-goto macros and opcode definitions
  • cs/Bytecode.cs - Opcode definitions and bytecode utilities

Build & Test

  • tools/build.sh - Main build orchestration script
    • tools/build.sh cs - build C# project
    • tools/build.sh transpile - generate C++ code from C# files
    • tools/build.sh cpp - build C++ project
  • tools/benchmark.sh - Performance benchmarking suite
  • cpp/Makefile - C++ build configuration with optimization flags
  • examples/*.msa - Assembly test programs (tuned for benchmarking)

Recent Major Fixes & Optimizations

Common Commands

# Full build and test
tools/build.sh all && tools/build.sh test

# Performance benchmarking
tools/benchmark.sh                    # Compare C#, C++ (switch), C++ (goto)

# Test specific dispatch method
tools/build.sh cpp on   # Force computed-goto
tools/build.sh cpp off  # Force switch-based

# Run programs with different output modes
./build/cpp/miniscript examples/test_calls.msa           # Clean output
./build/cpp/miniscript --debug examples/test_calls.msa   # Verbose debug output
./build/cpp/miniscript --test                            # Unit + integration test suites
./build/cpp/miniscript --help                            # Full option list

Development Notes

  • Always edit C# files in cs/ directory, never generated C++ directly, unless trying to pin down some C++-only crash; then you may hack the generated C++ code to gain understanding.
  • Never edit notes/DEV_LOG.md. That file is strictly the user's, and is written in the user's own voice; do not add, reword, or remove entries there, even when asked to "update the notes" after a change. Other files in notes/ (such as bugs.md) are fair game.
  • Memory management: runtime Values are handled by the custom mark/sweep GC and need no protection in ordinary code (there is no GC_PROTECT; the old shadow stack is gone). Use AddRoot/RetainValue only for a Value that must outlive its natural reachability, and shared_ptr for host app data. See MEMORY_SYSTEMS.md.
  • Coding standards: See CS_CODING_STANDARDS.md.

In general, do not use the transpiler unless instructed otherwise, as it is token-expensive and is more the user's purview. Do most edits in the C# code only, and notify the user when it's ready for transpilation and testing on the C++ side. If you are instructed to transpile and test, use tools/build.sh transpile followed by - Transpile after C# changes: tools/build.sh cpp.

Communication Style

Answer in a calm tone; avoid exclamation marks. Be careful not to prematurely declare success; instead, plainly describe what you believe to be done.

Whenever you're not sure what is wanted, or how best to approach something, stop and ask for clarification.

This context file helps maintain continuity across Claude Code sessions. Update as major features are implemented or architectural changes are made.