Skip to content

Commit 8f2aa8b

Browse files
fjtrujyfjtrujy
committed
Adding claude info
1 parent 9be6847 commit 8f2aa8b

1 file changed

Lines changed: 167 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
MASP (Assembly Preprocessor) is a fork of GASP (GNU Assembler Preprocessor) with modifications. It's a macro preprocessor for assembly language that adds directives, macros, and conditional assembly support before passing output to an assembler like GAS.
8+
9+
Key differences from GASP:
10+
- Default directive prefix is `\` instead of `.` (configurable via `-P/--prefixchar`)
11+
- Number prefix syntax changed (e.g., `0b0011` for binary instead of `B'0011`)
12+
- Macro syntax requires commas between arguments
13+
- Mode switching: `\masp` and `\gasp` directives to switch between syntaxes
14+
- No external dependencies (libiberty removed)
15+
16+
## Build Commands
17+
18+
### Standard build:
19+
```bash
20+
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
21+
cmake --build build -j
22+
```
23+
24+
The `masp` executable will be in `build/src/masp`.
25+
26+
### Build with AddressSanitizer (enabled by default):
27+
```bash
28+
cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
29+
cmake --build build -j
30+
```
31+
32+
### Build without AddressSanitizer:
33+
```bash
34+
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DENABLE_ASAN=OFF
35+
cmake --build build -j
36+
```
37+
38+
### Run tests:
39+
```bash
40+
# Run all tests
41+
ctest --test-dir build --output-on-failure
42+
43+
# Or use the 'check' target
44+
cmake --build build --target check
45+
```
46+
47+
**Important**: Unit tests only run when ASAN is enabled. Without ASAN, MASP has known memory corruption bugs that cause crashes. Tests are automatically skipped when `ENABLE_ASAN=OFF`.
48+
49+
### Install:
50+
```bash
51+
cmake --install build --prefix /usr/local
52+
```
53+
54+
## Architecture
55+
56+
### Core Components
57+
58+
1. **String Buffers (`sb.h`, `sb.c`)**
59+
- Custom string buffer implementation (`sb` struct)
60+
- Avoids null-terminated string manipulation issues
61+
- Provides efficient string growth and allocation
62+
- Used throughout for text manipulation
63+
64+
2. **Macro System (`macro.h`, `macro.c`)**
65+
- Handles macro definitions and expansions
66+
- `formal_entry`: describes macro formal arguments
67+
- `macro_entry`: describes complete macro with substitution text
68+
- Maintains hash tables for fast formal argument lookup
69+
- Supports nested macros (tracked via `macro_nest`)
70+
71+
3. **Hash Tables (`hash.h`, `hash.c`)**
72+
- Used for symbol lookup and macro storage
73+
- Generic hash table implementation
74+
75+
4. **Main Preprocessor (`masp.c`)**
76+
- ~3000+ lines of core preprocessing logic
77+
- Character classification system via `chartype[]` array with bit flags:
78+
- `FIRSTBIT`, `NEXTBIT`: identifier characters
79+
- `SEPBIT`, `WHITEBIT`: separators and whitespace
80+
- `COMMENTBIT`: comment characters
81+
- `BASEBIT`: base prefix characters
82+
- Directive processing system with keyword constants (K_EQU, K_MACRO, etc.)
83+
- Conditional assembly via `ifstack[]` (max 100 nesting levels)
84+
- Mode switching between MASP and GASP syntax
85+
- Number base conversion (0b, 0q, 0h, 0d, 0a prefixes)
86+
87+
5. **Compatibility Layer (`compat.h`, `compat.c`)**
88+
- Portability abstractions
89+
- Platform-specific implementations
90+
91+
### Build System
92+
93+
- CMake 3.15+ required
94+
- `src/CMakeLists.txt`: defines MASP_SOURCES, generates config.h
95+
- Compiler warnings are conditional (checked via CheckCCompilerFlag)
96+
- MinGW builds link against `gnurx` for POSIX regex support
97+
- ASAN is enabled by default (`-DENABLE_ASAN=ON`)
98+
- Optional UBSan in CI: `-fsanitize=undefined`
99+
100+
### Test Structure
101+
102+
- **Unit tests** (`test/unit/`):
103+
- `test_masp_cli.c`: in-process CLI tests (links against MASP object files)
104+
- `test_stress_parallel.c`: stress test for concurrent usage
105+
- Tests compile MASP sources directly to avoid CLI parsing issues
106+
- Only run when ASAN is enabled
107+
108+
- **Integration test files** (`test/*.vcl`):
109+
- Assembly files for testing preprocessor output
110+
- `test/include/`: self-contained test dependencies
111+
112+
### Memory Safety
113+
114+
**Critical**: MASP has known memory corruption bugs that cause crashes (SIGABRT) without AddressSanitizer. ASAN is enabled by default and should only be disabled for production builds where performance is critical.
115+
116+
When running with ASAN in CI/CD:
117+
- Leak detection is disabled (`detect_leaks=0`)
118+
- Known minor leaks (~36KB at exit) are not critical
119+
- Focus is on crashes, buffer overflows, and use-after-free
120+
121+
### CI/CD
122+
123+
GitHub Actions workflow (`.github/workflows/compilation.yml`):
124+
- Tests on macOS (ARM64, x86_64), Ubuntu, Windows (MinGW)
125+
- Matrix builds with/without ASAN
126+
- Tests only run when ASAN is enabled
127+
- ASAN options: `check_initialization_order=1:strict_string_checks=1:detect_leaks=0`
128+
129+
## Development Notes
130+
131+
### When modifying the preprocessor:
132+
133+
1. **Directive handling**: New directives are added in `masp.c`:
134+
- Define a K_* constant (e.g., `K_MASP`, `K_GASP`)
135+
- Add to the keyword processing system
136+
- Handle in the main processing loop
137+
138+
2. **Macro changes**: Be careful with macro argument handling:
139+
- Arguments are comma-separated
140+
- Escape sequences: `\,` for commas, `\\` for backslashes in macro args
141+
- String literals passed as-is (but `\` needs escaping)
142+
143+
3. **String operations**: Always use `sb_*` functions:
144+
- `sb_new()`, `sb_kill()` for allocation/deallocation
145+
- `sb_add_char()`, `sb_add_string()`, `sb_add_buffer()` for appending
146+
- `sb_reset()` to clear without deallocating
147+
- Never manipulate `sb.ptr` directly
148+
149+
4. **Testing strategy**:
150+
- Always build with ASAN during development
151+
- Run tests with `ctest --test-dir build --output-on-failure`
152+
- Tests are designed to catch memory corruption early
153+
- Add new test cases to `test/unit/test_masp_cli.c`
154+
155+
### Platform-specific concerns:
156+
157+
- **Windows/MinGW**: Requires `gnurx` library for POSIX regex
158+
- **macOS**: Tested on both ARM64 and Intel
159+
- **POSIX regex**: Used in `masp.c` (needs `<regex.h>`)
160+
161+
### Known limitations (from README):
162+
163+
- No comprehensive documentation
164+
- Inherited bugs from original GASP
165+
- MRI compatibility mode and alternate syntax deprecated
166+
- Macro comments can cause issues (avoid in macro definitions and calls)
167+
- Comments are not processed (syntax errors in comments are ignored)

0 commit comments

Comments
 (0)