feat: add CLAUDE.md

Signed-off-by: Amlal El Mahrouss <amlal@nekernel.org>

1 files changed, 274 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..582be65
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,274 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build System
+
+Nectar uses **NeBuild** (https://github.com/nekernel-org/nebuild) as its build system, configured via JSON files.
+
+### Building the Project
+
+```bash
+# Build CompilerKit library (required first)
+cd src/CompilerKit
+nebuild ck-posix.json    # Linux
+nebuild ck-osx.json      # macOS
+nebuild ck-osx-san.json  # macOS with sanitizers
+
+# Build DebuggerKit library
+cd src/DebuggerKit
+nebuild dk-posix.json    # POSIX systems
+nebuild dk-osx.json      # macOS
+nebuild dk-nekernel.json # NeKernel target
+
+# Build command-line tools (examples)
+cd src/CommandLine
+nebuild asm.json         # Assembler driver
+nebuild ld64.json        # Linker driver
+nebuild cppdrv.json      # Preprocessor driver
+nebuild pef-amd64-cxxdrv.json  # C++ compiler driver
+```
+
+### Testing
+
+Tests use CMake + Google Test:
+
+```bash
+# Run code generation tests
+cd test/test_01_codegen
+cmake . && make && ./CodegenTestBasic
+
+# Run linker tests
+cd test/test_02_linker
+cmake . && make && ./LinkerTestBasic
+```
+
+### Code Formatting
+
+**CRITICAL:** Always run `./format.sh` before committing. This uses clang-format to format all `.cc`, `.c`, `.h`, and `.inl` files.
+
+```bash
+./format.sh
+```
+
+## Architecture Overview
+
+Nectar is a compiler toolchain for the NeKernel operating system, producing **PEF (Preferred Executable Format)** executables from **AE (Advanced Executable)** object files.
+
+### Component Structure
+
+```
+src/
+├── CompilerKit/          # Core compiler infrastructure (library)
+│   ├── src/Assemblers/   # Multi-architecture assemblers
+│   ├── src/Compilers/    # C++ compiler frontend
+│   ├── src/Linkers/      # Dynamic linker (PEF format)
+│   └── src/Preprocessor/ # Generic preprocessor
+│
+├── DebuggerKit/          # Debugging infrastructure (library)
+│   └── src/              # POSIX/Mach and NeKernel debuggers
+│
+├── CommandLine/          # CLI tool frontends
+│   ├── asm.cc            # Assembler driver
+│   ├── ld64.cc           # Linker driver
+│   ├── cppdrv.cc         # Preprocessor driver
+│   ├── pef-amd64-cxxdrv.cc  # C++ compiler driver
+│   ├── dbg.cc            # User-space debugger
+│   └── kdbg.cc           # Kernel debugger
+│
+└── LibC++/               # C++ ABI runtime (header-only)
+```
+
+### Compilation Pipeline
+
+```
+Source (.cc) → Preprocessor (cppdrv) → Preprocessed (.pp)
+             → C++ Compiler (pef-amd64-cxxdrv) → Assembly (.masm)
+             → Assembler (asm) → Object File (.obj, AE format)
+             → Linker (ld64) → Executable (.exec, PEF format)
+```
+
+Example workflow from tests:
+```bash
+pef-amd64-cxxdrv sample.cc           # Compile to assembly
+asm -asm:x64 sample.cc.pp.masm       # Assemble to object
+ld64 -amd64 sample.cc.pp.obj -start __NECTAR_main -output main.exec  # Link
+```
+
+### Supported Architectures
+
+The project supports **5 CPU architectures**:
+- **AMD64** (x86-64) - Primary target
+- **ARM64** (AArch64)
+- **PowerPC** (64-bit POWER)
+- **64x0** - Open64x0 RISC architecture
+- **32x0** - 32-bit variant
+
+Each architecture has dedicated assembler implementations in `src/CompilerKit/src/Assemblers/Assembler+<ARCH>.cc`.
+
+## File Naming Conventions
+
+### Implementation Files
+- **Pattern:** `ClassName+Architecture.cc` or `ClassName+Format.cc`
+- Examples:
+  - `Assembler+AMD64.cc` - AMD64 assembler
+  - `CPlusPlusCompiler+AMD64.cc` - C++ compiler frontend for AMD64
+  - `DynamicLinker64+PEF.cc` - 64-bit linker for PEF format
+
+### Test Files
+- **Pattern:** `<name>.test.cc`
+- Examples: `codegen.test.cc`, `linker.test.cc`
+
+### Build Configuration Files
+- **Pattern:** `<component>-<platform>.json`
+- Examples: `ck-posix.json`, `dk-osx.json`, `asm.json`
+
+### File Extensions
+- `.cc` - C++ source
+- `.h` - Headers
+- `.inl` - Inline implementations
+- `.obj` - AE object files
+- `.exec` - PEF executables
+- `.pp` - Preprocessed files
+- `.masm`, `.s`, `.S`, `.x64`, `.64x`, `.32x` - Assembly files
+
+## Code Style and Patterns
+
+### Type Aliases (from PreConfig.h)
+Use these instead of standard types:
+- `Int32`, `UInt32`, `Int64`, `UInt64` instead of `int`, `unsigned`, etc.
+- `Char` instead of `char`
+- `SizeType` instead of `size_t`
+- `STLString` instead of `std::string`
+- `VoidPtr`, `UIntPtr` for pointers
+
+### Common Macros
+```cpp
+// Class semantics
+NECTAR_COPY_DEFAULT(ClassName)
+NECTAR_COPY_DELETE(ClassName)
+NECTAR_MOVE_DEFAULT(ClassName)
+NECTAR_MOVE_DELETE(ClassName)
+
+// Assertions and utilities
+MUST_PASS(expression)
+PACKED  // For packed structs
+
+// Interface patterns
+CK_ASSEMBLY_INTERFACE       // : public IAssembly
+CK_COMPILER_FRONTEND        // : public ICompilerFrontend
+DK_DEBUGGER_CONTRACT        // : public IDebuggerContract
+```
+
+### Error Codes
+```cpp
+NECTAR_SUCCESS = 0
+NECTAR_EXEC_ERROR = -30
+NECTAR_FILE_NOT_FOUND = -31
+NECTAR_UNIMPLEMENTED = -36
+NECTAR_INVALID_ARCH = -38
+```
+
+### Reference Management
+```cpp
+StrongRef<T> strong_ref(new T());  // Owns the pointer
+WeakRef<T> weak_ref = strong_ref.Leak();  // Non-owning reference
+```
+
+## Key Headers and Utilities
+
+### CompilerKit
+- `/include/CompilerKit/PEF.h` - PEF executable format definitions
+- `/include/CompilerKit/AE.h` - AE object format definitions
+- `/include/CompilerKit/AST.h` - Abstract syntax tree for C++ compiler
+- `/include/CompilerKit/Detail/<ARCH>.h` - Architecture-specific definitions
+- `/include/CompilerKit/Utilities/Compiler.h` - Common compiler helpers
+- `/include/CompilerKit/ErrorOr.h` - Error handling utilities
+
+### DebuggerKit
+- `/include/DebuggerKit/DebuggerContract.h` - Debugger interface contracts
+
+### Common Patterns in Code
+
+**Error handling:**
+```cpp
+if (error_condition) {
+  Detail::print_error("reason", "filename");
+  return NECTAR_EXEC_ERROR;
+}
+```
+
+**Factory pattern for assemblers:**
+```cpp
+AssemblyFactory factory;
+factory.Mount(WeakRef<IAssembly>(new AMD64Assembler()));
+factory.Compile(sourceFile, AssemblyFactory::kArchAMD64);
+```
+
+## NeBuild Configuration Structure
+
+Example JSON configuration:
+```json
+{
+  "compiler_path": "clang++",
+  "compiler_std": "c++20",
+  "headers_path": ["../../include/CompilerKit", "../../include/"],
+  "sources_path": ["src/*.cc", "src/*/*.cc"],
+  "output_name": "/usr/lib/libCompilerKit.so",
+  "compiler_flags": ["-fPIC", "-shared"],
+  "cpp_macros": ["__NECTAR__=202505", "CK_USE_STRUCTS=1"],
+  "run_after_build": true
+}
+```
+
+## Important Constants
+
+- **C++ Standard:** C++20
+- **Nectar Version Macro:** `__NECTAR__=202505`
+- **PEF Magic:** `"Open"` (or `"nepO"` for FAT binaries)
+- **AE Magic:** `"AEF"`
+- **Default PEF Base Address:** `0x40000000`
+- **Entry Point Symbol:** `__ImageStart`
+- **Main Function Symbol:** `__NECTAR_main`
+
+## Git Workflow
+
+- **Main Branch:** `stable` (use this for PRs)
+- **Development Branch:** `develop`
+- **CI:** Runs on push/PR to `develop` branch
+- **Commit Convention:** Run `./format.sh` before every commit
+
+## Project-Specific Context
+
+### Output Formats
+- **PEF (Preferred Executable Format):** Custom executable format for NeKernel
+  - Extensions: `.exec` (executable), `.dylib` (shared), `.sys` (driver)
+  - Sections: `.code64`, `.data64`, `.zero64` (and 128-bit variants)
+
+- **AE (Advanced Executable):** Object file format
+  - Relocatable by offset
+  - Contains code, data, and BSS records
+  - Symbol length: 256 bytes
+
+### Adding New Features
+
+**New assembler instruction:**
+- Architecture opcodes: `/include/CompilerKit/Detail/<ARCH>.h`
+- Implementation: `/src/CompilerKit/src/Assemblers/Assembler+<ARCH>.cc`
+
+**Modifying C++ compiler:**
+- Frontend: `/src/CompilerKit/src/Compilers/CPlusPlusCompiler+AMD64.cc`
+- AST: `/include/CompilerKit/AST.h`
+
+**Modifying linker:**
+- Implementation: `/src/CompilerKit/src/Linkers/DynamicLinker64+PEF.cc`
+- Format specs: `/include/CompilerKit/PEF.h` and `/include/CompilerKit/AE.h`
+
+## Dependencies
+
+- Clang (C++20 support)
+- Git
+- Boost
+- NeBuild (https://github.com/nekernel-org/nebuild)
+- Doxygen (for documentation)
+- CoreUtils