[initial]

1 files changed, 492 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d38bee2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,492 @@
+# BoltDBG
+
+⚡ A lightning-fast, modern graphical debugger for C programs built from the ground up with Dear ImGui.
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)
+![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
+![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)
+
+## Overview
+
+BoltDBG is a comprehensive debugging tool designed to streamline the development and troubleshooting of C applications. Built entirely from scratch with custom debug information parsing and powered by Dear ImGui, it delivers a responsive, modern interface with the performance and control serious developers demand.
+
+### Why BoltDBG?
+
+- **Built from Scratch**: Custom debug information parser with complete control over implementation
+- **Lightning Fast**: Optimized rendering with Dear ImGui for smooth 60+ FPS debugging
+- **Cross-Platform**: Native support for Linux, macOS, and Windows
+- **Modern UI**: Clean, responsive interface with docking, customizable layouts, and themes
+- **Developer-Focused**: Designed by developers, for developers
+
+### Key Features
+
+- **Visual Breakpoint Management**: Set, disable, and remove breakpoints with a single click
+- **Real-time Variable Inspection**: Monitor variable values and memory contents as your program executes
+- **Call Stack Visualization**: Navigate through function calls with a clear, hierarchical view
+- **Step-by-Step Execution**: Fine-grained control with step over, step into, and step out functionality
+- **Memory Viewer**: Inspect raw memory regions with hexadecimal and ASCII representations
+- **Register Display**: View and track CPU register states during execution
+- **Expression Evaluation**: Evaluate arbitrary C expressions in the current execution context
+- **Watchpoints**: Monitor specific variables and break when they change
+- **Syntax Highlighting**: Color-coded source code display for improved readability
+- **Multi-threaded Debugging**: Debug applications with multiple threads simultaneously
+- **Disassembly View**: See the assembly code alongside your source
+- **Customizable Layouts**: Drag-and-drop panels to create your perfect workspace
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Building from Source](#building-from-source)
+- [Usage](#usage)
+- [Features in Detail](#features-in-detail)
+- [Configuration](#configuration)
+- [Keyboard Shortcuts](#keyboard-shortcuts)
+- [Architecture](#architecture)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+### Linux
+
+#### Ubuntu/Debian
+```bash
+sudo apt-get update
+sudo apt-get install boltdbg
+```
+
+#### Fedora/RHEL
+```bash
+sudo dnf install boltdbg
+```
+
+#### Arch Linux
+```bash
+yay -S boltdbg
+```
+
+### macOS
+
+```bash
+brew install boltdbg
+```
+
+### Windows
+
+Download the installer from the [releases page](https://github.com/yourusername/boltdbg/releases) and run the setup wizard.
+
+Alternatively, using Chocolatey:
+```powershell
+choco install boltdbg
+```
+
+## Quick Start
+
+1. **Launch the debugger**:
+   ```bash
+   boltdbg
+   ```
+
+2. **Open your C program**:
+   - Click `File > Open` or press `Ctrl+O`
+   - Select your compiled executable (with debug symbols)
+
+3. **Set a breakpoint**:
+   - Click on the line number where you want to pause execution
+
+4. **Start debugging**:
+   - Click the `Run` button or press `F5`
+   - Your program will execute until it hits a breakpoint
+
+5. **Inspect and control**:
+   - Use the toolbar buttons to step through code
+   - View variables in the Variables panel
+   - Check the call stack in the Stack panel
+
+## Building from Source
+
+### Prerequisites
+
+**Required:**
+- CMake 3.15+
+- C++17 compatible compiler (GCC 9.0+, Clang 10.0+, MSVC 2019+)
+- Git
+
+**Platform-Specific:**
+- **Linux**: X11 development libraries (`libx11-dev`, `libxrandr-dev`, `libxinerama-dev`, `libxcursor-dev`, `libxi-dev`)
+- **macOS**: Xcode Command Line Tools
+- **Windows**: Windows SDK
+
+### Build Steps
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/boltdbg.git
+cd boltdbg
+
+# Initialize submodules (Dear ImGui)
+git submodule update --init --recursive
+
+# Create build directory
+mkdir build && cd build
+
+# Configure
+cmake .. -DCMAKE_BUILD_TYPE=Release
+
+# Build
+cmake --build . -j$(nproc)
+
+# Install (optional)
+sudo cmake --install .
+```
+
+### Build Options
+
+- `-DBOLTDBG_BUILD_TESTS=ON`: Build with unit tests
+- `-DBOLTDBG_BUILD_DOCS=ON`: Generate documentation
+- `-DBOLTDBG_ENABLE_ASAN=ON`: Enable AddressSanitizer for development
+- `-DCMAKE_INSTALL_PREFIX=/usr/local`: Set installation directory
+
+### Dependencies
+
+BoltDBG uses minimal dependencies to ensure fast builds and easy maintenance:
+
+- **Dear ImGui** (included as submodule): UI framework
+- **GLFW** (included): Window and input handling
+- **OpenGL 3.3+**: Graphics rendering (system)
+
+All dependencies are either bundled or available on all target platforms.
+
+## Usage
+
+### Basic Debugging Session
+
+```bash
+# Debug a program with arguments
+boltdbg ./myprogram arg1 arg2
+
+# Attach to a running process
+boltdbg --attach <PID>
+
+# Load a core dump
+boltdbg ./myprogram --core core.dump
+```
+
+### Command Line Options
+
+```
+Usage: boltdbg [OPTIONS] [PROGRAM] [ARGS...]
+
+Options:
+  -h, --help              Show this help message
+  -v, --version           Display version information
+  -a, --attach PID        Attach to running process
+  -c, --core FILE         Load core dump file
+  -p, --project FILE      Open project file
+  -s, --symbols DIR       Additional symbol directory
+  --remote HOST:PORT      Connect to remote debugging session
+  --headless              Run without GUI (for automation)
+  --config FILE           Use alternate configuration file
+```
+
+## Features in Detail
+
+### Breakpoints
+
+Set breakpoints by clicking on line numbers or using the breakpoint manager:
+
+- **Line Breakpoints**: Pause execution at specific lines
+- **Conditional Breakpoints**: Break only when conditions are met (e.g., `x > 100`)
+- **Function Breakpoints**: Break when entering specific functions
+- **Hardware Breakpoints**: Limited count, faster execution
+- **Hit Count**: Break after N hits
+
+### Variable Inspection
+
+The Variables panel displays:
+- Local variables in the current scope
+- Global variables
+- Function arguments
+- Dynamically allocated memory
+- Array and structure contents with expandable tree view
+- Pointer following with recursive visualization
+- Custom type pretty-printers
+
+### Memory Viewer
+
+Access the memory viewer via `View > Memory` or `Ctrl+M`:
+- Hexadecimal dump with configurable bytes per row (8, 16, 32)
+- ASCII representation alongside hex values
+- Navigate to specific addresses
+- Follow pointers with right-click menu
+- Watch memory regions for changes
+- Multiple memory windows with different views
+
+### Disassembly View
+
+View assembly code alongside source:
+- Syntax-highlighted assembly
+- Address and byte code display
+- Jump target visualization
+- Interleaved source and assembly mode
+- Register value annotations
+
+### Expression Evaluator
+
+Evaluate C expressions in the current context:
+- Support for all C operators
+- Function calls (with side effects)
+- Type casting
+- Pointer dereferencing
+- Expression history
+
+### Customizable Layout
+
+BoltDBG uses Dear ImGui's docking system:
+- Drag and drop panels anywhere
+- Create custom layouts for different workflows
+- Save and load layout presets
+- Multi-monitor support
+- Tab groups for related panels
+
+## Configuration
+
+Configuration files are located at:
+- **Linux**: `~/.config/boltdbg/config.json`
+- **macOS**: `~/Library/Application Support/boltdbg/config.json`
+- **Windows**: `%APPDATA%\boltdbg\config.json`
+
+### Example Configuration
+
+```json
+{
+  "editor": {
+    "font": "JetBrains Mono",
+    "font_size": 14,
+    "theme": "dark",
+    "show_line_numbers": true,
+    "highlight_current_line": true,
+    "tab_size": 4
+  },
+  "debugger": {
+    "break_on_launch": false,
+    "show_disassembly": false,
+    "step_into_system_calls": false,
+    "auto_load_symbols": true,
+    "follow_forks": false
+  },
+  "ui": {
+    "theme": "dark",
+    "vsync": true,
+    "fps_target": 60,
+    "dpi_scale": 1.0,
+    "layout_preset": "default"
+  },
+  "memory": {
+    "bytes_per_row": 16,
+    "show_ascii": true,
+    "uppercase_hex": true
+  }
+}
+```
+
+## Keyboard Shortcuts
+
+| Action | Shortcut |
+|--------|----------|
+| Start/Continue | `F5` |
+| Step Over | `F10` |
+| Step Into | `F11` |
+| Step Out | `Shift+F11` |
+| Toggle Breakpoint | `F9` |
+| Stop Debugging | `Shift+F5` |
+| Restart | `Ctrl+Shift+F5` |
+| Run to Cursor | `Ctrl+F10` |
+| Open File | `Ctrl+O` |
+| Save Layout | `Ctrl+S` |
+| Find | `Ctrl+F` |
+| Go to Line | `Ctrl+G` |
+| Go to Address | `Ctrl+Shift+G` |
+| Toggle Disassembly | `Ctrl+D` |
+
+## Architecture
+
+BoltDBG is built with a modular architecture:
+
+### Core Components
+
+```
+boltdbg/
+├── src/
+│   ├── core/           # Core debugger engine
+│   │   ├── debugger.cpp
+│   │   ├── breakpoint.cpp
+│   │   ├── process.cpp
+│   │   └── thread.cpp
+│   ├── symbols/        # Custom symbol parser
+│   │   ├── parser.cpp
+│   │   ├── symbol_table.cpp
+│   │   └── types.cpp
+│   ├── platform/       # Platform-specific code
+│   │   ├── linux/      # ptrace implementation
+│   │   ├── macos/      # ptrace implementation
+│   │   └── windows/    # Debug API implementation
+│   ├── ui/             # Dear ImGui interface
+│   │   ├── main_window.cpp
+│   │   ├── code_view.cpp
+│   │   ├── variables_view.cpp
+│   │   ├── memory_view.cpp
+│   │   ├── registers_view.cpp
+│   │   └── callstack_view.cpp
+│   └── main.cpp
+└── external/
+    ├── imgui/          # Dear ImGui submodule
+    └── glfw/           # GLFW submodule
+```
+
+### Symbol System
+
+The custom symbol system handles:
+- Parsing debug information from executables
+- Building symbol tables for functions and variables
+- Source line mapping
+- Type information storage and lookup
+- Address-to-symbol resolution
+
+### Platform Layer
+
+Platform-specific implementations for:
+- **Process control**: ptrace on Linux/macOS, Debug API on Windows
+- **Memory reading/writing**: Direct process memory access
+- **Register access**: Hardware register read/write
+- **Signal/exception handling**: Breakpoint and fault handling
+- **Thread enumeration**: Multi-threaded program support
+
+## Troubleshooting
+
+### Program not stopping at breakpoints
+
+**Issue**: Breakpoints are ignored during execution.
+
+**Solutions**:
+- Ensure your program was compiled with debug symbols (`-g` flag)
+- Verify the source file path matches the compiled binary
+- Check that optimizations aren't removing code (`-O0` for debugging)
+- Confirm debug symbols are embedded in the executable
+
+### Cannot attach to process
+
+**Issue**: Permission denied when attaching to a process.
+
+**Solutions**:
+- Run the debugger with elevated privileges (use `sudo` cautiously)
+- On Linux, check ptrace_scope: `sudo sysctl -w kernel.yama.ptrace_scope=0`
+- Ensure the target process isn't already being debugged
+
+### Missing symbols
+
+**Issue**: Variable names show as addresses or are unavailable.
+
+**Solutions**:
+- Install debug symbol packages for system libraries
+- Add symbol search paths via `-s` option or in settings
+- Rebuild your program with `-g` flag
+- Verify debug symbols weren't stripped from the binary
+
+### Performance Issues
+
+**Issue**: Debugger feels slow or unresponsive.
+
+**Solutions**:
+- Disable VSync in settings if input feels laggy
+- Reduce the number of auto-updated variables
+- Reduce the number of active watchpoints
+- Close unused panels to free resources
+- Check GPU drivers are up to date
+
+### Display Issues
+
+**Issue**: UI elements appear blurry or incorrectly sized.
+
+**Solutions**:
+- Adjust DPI scaling in settings
+- Try setting `dpi_scale` to match your monitor
+- On Windows, disable display scaling override
+- Update graphics drivers
+
+## Contributing
+
+We welcome contributions from the community! Here's how you can help:
+
+### Reporting Bugs
+
+Submit bug reports on our [issue tracker](https://github.com/yourusername/boltdbg/issues) with:
+- Detailed description of the issue
+- Steps to reproduce
+- Expected vs actual behavior
+- System information (OS, version, compiler)
+- Relevant logs or screenshots
+- Sample program that demonstrates the issue
+
+### Submitting Pull Requests
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass (`make test`)
+6. Run the formatter (`make format`)
+7. Commit with clear messages (`git commit -m 'Add amazing feature'`)
+8. Push to your fork (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
+
+### Development Guidelines
+
+- Follow the C++17 standard
+- Use the existing code style (run `clang-format`)
+- Write unit tests for new features
+- Update documentation as needed
+- Keep commits focused and atomic
+- Write descriptive commit messages
+
+### Areas to Contribute
+
+- Platform support improvements
+- Symbol parsing enhancements
+- UI/UX improvements
+- Performance optimizations
+- Documentation and examples
+- Bug fixes
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built with [Dear ImGui](https://github.com/ocornut/imgui) for the user interface
+- Window management via [GLFW](https://www.glfw.org/)
+- Inspired by [GDB](https://www.gnu.org/software/gdb/), [LLDB](https://lldb.llvm.org/), and [RemedyBG](https://remedybg.itch.io/remedybg)
+
+## Support
+
+- **Documentation**: [https://boltdbg.readthedocs.io](https://boltdbg.readthedocs.io)
+- **Discord**: [Join our community](https://discord.gg/yourdiscord)
+- **Discussions**: [GitHub Discussions](https://github.com/yourusername/boltdbg/discussions)
+- **Issues**: [GitHub Issues](https://github.com/yourusername/boltdbg/issues)
+
+## Roadmap
+
+- [ ] Remote debugging over network
+- [ ] Time-travel debugging (record and replay)
+- [ ] Plugin system for extensibility
+- [ ] Integration with popular editors (VS Code, Vim, Neovim)
+- [ ] Performance profiling tools
+- [ ] Enhanced symbol parsing for optimized code
+- [ ] Docker container debugging
+- [ ] Kernel debugging support
+
+---