https://github.com/krystophny created https://github.com/llvm/llvm-project/pull/150837
None >From e22c3e4801fd633b36bd8d2dad9eada658781606 Mon Sep 17 00:00:00 2001 From: Christopher Albert <alb...@alumni.tugraz.at> Date: Sun, 27 Jul 2025 17:34:38 +0200 Subject: [PATCH 1/3] Add strategic documentation for LLDB Fortran support implementation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - LLDB_FORTRAN.md: Strategic design document outlining 4-phase approach - BACKLOG.md: Detailed TDD implementation plan with epics and stories - CLAUDE.md: Enhanced with LLDB-specific development guidelines Addresses issue #109119: Fortran language support in lldb 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <nore...@anthropic.com> --- BACKLOG.md | 357 ++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 216 +++++++++++++++++++++++++++++ LLDB_FORTRAN.md | 210 ++++++++++++++++++++++++++++ 3 files changed, 783 insertions(+) create mode 100644 BACKLOG.md create mode 100644 CLAUDE.md create mode 100644 LLDB_FORTRAN.md diff --git a/BACKLOG.md b/BACKLOG.md new file mode 100644 index 0000000000000..17b06649bbff0 --- /dev/null +++ b/BACKLOG.md @@ -0,0 +1,357 @@ +# LLDB Fortran Support - Implementation Backlog + +## Epic 1: Development Environment Setup +**Status**: 🔵 Ready +**Goal**: Establish efficient development and testing environment + +### Story 1.1: Minimal Build Configuration +- [ ] Create optimal CMake configuration for Fortran LLDB development +- [ ] Document build time and disk space requirements +- [ ] Verify build works with both Debug and Release configurations +- [ ] Test with different generators (Ninja, Make) + +**Acceptance Criteria**: +- Build completes in under 30 minutes on standard hardware +- Only necessary targets are built (LLDB + minimal dependencies) +- Debug symbols available for development + +**Test Cases**: +- Build with gfortran available +- Build with flang available +- Build without Fortran compilers (should still work) + +### Story 1.2: Test Infrastructure Foundation +- [ ] Set up basic test structure in `lldb/test/API/lang/fortran/` +- [ ] Create simple Fortran test programs (.f90 files) +- [ ] Establish lit test configuration +- [ ] Add CMake integration for Fortran tests + +**Acceptance Criteria**: +- Test directory structure follows LLDB conventions +- Tests can be run individually and in suites +- CI-friendly test execution + +**Test Cases**: +- Run single Fortran test +- Run full Fortran test suite +- Tests work with both gfortran and flang + +### Story 1.3: Continuous Integration Setup +- [ ] Create GitHub Actions workflow for Fortran tests +- [ ] Set up test matrix (multiple compilers, platforms) +- [ ] Configure test result reporting +- [ ] Add performance benchmarking + +**Acceptance Criteria**: +- Tests run automatically on PR submission +- Results clearly visible in PR status +- Performance regressions are detected + +--- + +## Epic 2: Phase 1 - Minimal Viable Plugin (MVP) +**Status**: 🔵 Ready +**Goal**: Eliminate "no plugin" warning, basic language recognition + +### Story 2.1: Plugin Registration Infrastructure (RED) +- [ ] Create `lldb/source/Plugins/Language/Fortran/` directory structure +- [ ] Implement basic `FortranLanguage.h` class declaration +- [ ] Add plugin registration in PluginManager +- [ ] Write failing test for language recognition + +**Acceptance Criteria**: +- LLDB recognizes Fortran as a supported language +- No "unsupported language" warnings for Fortran files +- Plugin loads without errors + +**Test Cases (RED phase)**: +```python +# Test: test_fortran_language_recognition.py +def test_fortran_language_detected(self): + """Test that LLDB recognizes Fortran source files""" + # This should FAIL initially + self.expect("settings show target.language", + substrs=["fortran"]) +``` + +### Story 2.2: Language Type Recognition (GREEN) +- [ ] Implement `GetLanguageType()` method +- [ ] Add support for all Fortran standards (F77, F90, F95, F2003, F2008, F2018) +- [ ] Implement source file extension recognition +- [ ] Make the RED test pass + +**Acceptance Criteria**: +- LLDB correctly identifies Fortran language from DWARF +- All Fortran file extensions recognized (.f, .f90, .f95, etc.) +- Language enum values properly handled + +**Test Cases (GREEN phase)**: +```python +def test_fortran_file_extensions(self): + """Test recognition of various Fortran file extensions""" + extensions = ['.f', '.f90', '.f95', '.f03', '.f08', '.f18'] + for ext in extensions: + # Should now PASS + self.assertTrue(is_fortran_file(f"test{ext}")) +``` + +### Story 2.3: Basic Plugin Methods (REFACTOR) +- [ ] Implement required Language base class methods +- [ ] Add proper error handling and logging +- [ ] Optimize plugin loading performance +- [ ] Add comprehensive documentation + +**Acceptance Criteria**: +- All Language interface methods implemented +- Code follows LLVM coding standards +- No memory leaks or performance regressions + +--- + +## Epic 3: Phase 2 - Type System Foundation +**Status**: ⏳ Waiting +**Dependencies**: Epic 2 complete + +### Story 3.1: DWARF Fortran Type Parsing (RED) +- [ ] Research DWARF format for Fortran types +- [ ] Write failing tests for COMPLEX type detection +- [ ] Write failing tests for CHARACTER type detection +- [ ] Write failing tests for Fortran array types + +**Test Cases (RED phase)**: +```python +def test_complex_variable_display(self): + """Test COMPLEX variable is displayed correctly""" + # Should FAIL initially - shows as unknown type + self.expect("frame variable complex_var", + substrs=["(1.0, 2.0)"]) # Expected format +``` + +### Story 3.2: COMPLEX Type Support (GREEN) +- [ ] Implement COMPLEX type formatter +- [ ] Handle both single and double precision COMPLEX +- [ ] Support real and imaginary part access +- [ ] Make COMPLEX tests pass + +**Acceptance Criteria**: +- COMPLEX variables display as "(real, imag)" format +- Individual real/imaginary parts accessible +- Both COMPLEX and DOUBLE COMPLEX supported + +### Story 3.3: CHARACTER Type Support (GREEN) +- [ ] Implement CHARACTER type formatter +- [ ] Handle fixed-length CHARACTER variables +- [ ] Support CHARACTER array display +- [ ] Handle character length attribute from DWARF + +**Acceptance Criteria**: +- CHARACTER variables show string content and length +- Null termination handled correctly +- CHARACTER arrays display properly + +### Story 3.4: LOGICAL Type Support (GREEN) +- [ ] Implement LOGICAL type formatter +- [ ] Map LOGICAL values to .TRUE./.FALSE. +- [ ] Handle different LOGICAL kinds + +**Acceptance Criteria**: +- LOGICAL variables display as .TRUE. or .FALSE. +- Different LOGICAL kinds supported + +### Story 3.5: Basic Array Support (GREEN) +- [ ] Implement Fortran array bounds display +- [ ] Show array dimensions and size +- [ ] Handle 1-based indexing display +- [ ] Support multi-dimensional arrays + +**Acceptance Criteria**: +- Arrays show bounds and dimensions +- 1-based indexing properly displayed +- Multi-dimensional arrays readable + +### Story 3.6: Type System Refactoring (REFACTOR) +- [ ] Optimize type detection performance +- [ ] Consolidate common formatter code +- [ ] Add comprehensive type system tests +- [ ] Document type system architecture + +--- + +## Epic 4: Phase 3 - Expression Evaluation +**Status**: ⏳ Waiting +**Dependencies**: Epic 3 complete + +### Story 4.1: Basic Expression Parser (RED) +- [ ] Write failing tests for simple Fortran expressions +- [ ] Research LLDB expression evaluation architecture +- [ ] Design Fortran expression parser interface + +**Test Cases (RED phase)**: +```python +def test_fortran_expression_evaluation(self): + """Test basic Fortran expression evaluation""" + # Should FAIL initially + self.expect("expression -- my_var + 1", + substrs=["3"]) # If my_var = 2 +``` + +### Story 4.2: Case-Insensitive Identifier Resolution (GREEN) +- [ ] Implement case-insensitive variable lookup +- [ ] Handle Fortran naming conventions +- [ ] Support compiler-specific name mangling + +**Acceptance Criteria**: +- Variables accessible regardless of case in expression +- Proper symbol resolution for different compilers + +### Story 4.3: Fortran Operators (GREEN) +- [ ] Implement Fortran-specific operators (**, .EQ., .NE., etc.) +- [ ] Handle operator precedence +- [ ] Support logical operators (.AND., .OR., .NOT.) + +**Acceptance Criteria**: +- All Fortran operators work in expressions +- Correct operator precedence +- Logical operations produce LOGICAL results + +### Story 4.4: Basic Intrinsic Functions (GREEN) +- [ ] Implement SIZE intrinsic function +- [ ] Implement LBOUND/UBOUND intrinsics +- [ ] Implement SHAPE intrinsic +- [ ] Add LEN intrinsic for CHARACTER + +**Acceptance Criteria**: +- Array intrinsics return correct values +- Character intrinsics work properly +- Error handling for invalid arguments + +--- + +## Epic 5: Phase 4 - Advanced Features +**Status**: ⏳ Waiting +**Dependencies**: Epic 4 complete + +### Story 5.1: Derived Type Support +- [ ] Parse Fortran derived types from DWARF +- [ ] Display derived type components +- [ ] Support type-bound procedures +- [ ] Handle inheritance + +### Story 5.2: Module and Interface Support +- [ ] Support module variable access +- [ ] Handle USE association +- [ ] Support interface blocks +- [ ] Generic procedure resolution + +### Story 5.3: Advanced Array Features +- [ ] Array sections and slicing +- [ ] Assumed-shape and deferred-shape arrays +- [ ] Allocatable and pointer arrays +- [ ] Array intrinsic functions + +### Story 5.4: Parameterized Derived Types (PDTs) +- [ ] Support length and kind parameters +- [ ] Handle parameterized type instantiation +- [ ] Display parameter values + +--- + +## Epic 6: Documentation and Community +**Status**: 🔵 Ready (parallel to development) + +### Story 6.1: User Documentation +- [ ] Create Fortran debugging tutorial +- [ ] Document limitations and known issues +- [ ] Provide compiler-specific guidance +- [ ] Add troubleshooting guide + +### Story 6.2: Developer Documentation +- [ ] Document plugin architecture decisions +- [ ] Create contribution guidelines +- [ ] Add design rationale documents +- [ ] Provide extending/modifying guide + +### Story 6.3: Community Engagement +- [ ] Regular updates to issue #109119 +- [ ] Engage with LLVM community for feedback +- [ ] Present at LLVM conferences +- [ ] Coordinate with Flang team + +--- + +## Definition of Done + +For each story to be considered complete: + +### Code Quality +- [ ] All tests pass (unit + integration) +- [ ] Code review approved +- [ ] Performance impact assessed +- [ ] Memory leak testing passed + +### Testing +- [ ] Red-Green-Refactor cycle completed +- [ ] Test coverage > 80% for new code +- [ ] Tests work with gfortran and flang +- [ ] Edge cases covered + +### Documentation +- [ ] Code properly commented +- [ ] User-facing features documented +- [ ] Design decisions recorded +- [ ] Known limitations noted + +### Integration +- [ ] CI tests pass +- [ ] No regressions in existing functionality +- [ ] Follows LLVM coding standards +- [ ] Ready for upstream submission + +--- + +## Risk Register + +### High-Risk Items +- **Performance Impact**: Adding language support could slow LLDB + - *Mitigation*: Profile carefully, implement lazy loading +- **Compiler Compatibility**: gfortran vs flang differences + - *Mitigation*: Test with both, abstract differences +- **DWARF Complexity**: Fortran DWARF can be complex + - *Mitigation*: Start simple, add complexity incrementally + +### Medium-Risk Items +- **Community Acceptance**: Changes may be rejected upstream + - *Mitigation*: Engage early, follow guidelines strictly +- **Maintenance Burden**: Large codebase changes + - *Mitigation*: Focus on clean, maintainable code + +### Low-Risk Items +- **Build System Changes**: CMake modifications needed + - *Mitigation*: Follow existing patterns + +--- + +## Sprint Planning + +### Sprint 1 (2 weeks): Environment Setup +- Epic 1 complete +- Story 2.1 started + +### Sprint 2 (2 weeks): MVP Foundation +- Stories 2.1-2.2 complete +- Story 2.3 started + +### Sprint 3 (2 weeks): MVP Complete +- Story 2.3 complete +- Story 3.1 started + +### Sprint 4-6 (6 weeks): Type System +- Epic 3 complete + +### Sprint 7-9 (6 weeks): Expression Evaluation +- Epic 4 complete + +### Sprint 10+ (ongoing): Advanced Features +- Epic 5 progressive implementation + +This backlog provides a clear roadmap following TDD principles while ensuring systematic progress toward full Fortran support in LLDB. \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000000..a5b056426e32d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,216 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Build System and Common Commands + +LLVM uses CMake as its build system. The typical workflow involves: + +**Initial Configuration:** +```bash +# Configure with Ninja (most developers use this) +cmake -S llvm -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_ASSERTIONS=ON + +# Build specific projects (example with Clang and LLD) +cmake -S llvm -B build -G Ninja -DLLVM_ENABLE_PROJECTS="clang;lld" -DCMAKE_BUILD_TYPE=Release +``` + +**Building:** +```bash +# Build everything +cmake --build build +# Or using ninja directly +ninja -C build + +# Build specific targets +ninja -C build llvm-opt clang +``` + +**Running Tests:** +```bash +# Run all LLVM regression tests +ninja -C build check-llvm + +# Run all unit tests +ninja -C build check-llvm-unit + +# Run specific project tests +ninja -C build check-clang +ninja -C build check-lld + +# Run all tests (unit + regression) +ninja -C build check-all + +# Run individual tests with lit +llvm-lit llvm/test/Analysis/BasicAA/ +llvm-lit path/to/specific/test.ll +``` + +**Key CMake Options:** +- `LLVM_ENABLE_PROJECTS`: Semicolon-separated list of projects to build (clang, lld, lldb, etc.) +- `LLVM_TARGETS_TO_BUILD`: Target architectures to build (default: "all") +- `CMAKE_BUILD_TYPE`: Debug, Release, RelWithDebInfo, MinSizeRel +- `LLVM_ENABLE_ASSERTIONS`: ON/OFF (default ON for Debug builds) +- `LLVM_USE_LINKER=lld`: Use LLD linker for faster linking + +## Architecture Overview + +**Major Components:** +- **llvm/**: Core LLVM infrastructure (IR, passes, code generation, tools) +- **clang/**: C/C++/Objective-C compiler frontend +- **clang-tools-extra/**: Additional Clang-based tools (clang-tidy, clangd, etc.) +- **lld/**: LLVM linker +- **lldb/**: LLVM debugger +- **compiler-rt/**: Runtime libraries (sanitizers, profiling, etc.) +- **libcxx/**: C++ standard library implementation +- **libcxxabi/**: C++ ABI library +- **polly/**: Polyhedral optimizer +- **mlir/**: Multi-Level IR framework +- **flang/**: Fortran frontend +- **bolt/**: Binary optimization and layout tool + +**LLVM Core Structure:** +- **lib/**: Core implementation (Analysis, Transforms, CodeGen, etc.) +- **include/llvm/**: Public headers +- **tools/**: Command-line tools (opt, llc, llvm-dis, etc.) +- **test/**: Regression tests organized by component +- **unittests/**: Unit tests using Google Test + +**Key Directories in llvm/lib/:** +- `Analysis/`: Various analysis passes +- `Transforms/`: Optimization passes (IPO, Scalar, Vectorize, etc.) +- `CodeGen/`: Code generation framework and target-specific backends +- `Target/`: Architecture-specific backends (X86, AArch64, ARM, etc.) +- `IR/`: LLVM IR core classes and utilities +- `Support/`: General utilities and data structures + +## Testing Infrastructure + +**Test Organization:** +- **Regression tests**: `llvm/test/` - FileCheck-based tests for specific functionality +- **Unit tests**: `llvm/unittests/` - Google Test-based tests for individual components +- **Integration tests**: Use lit (LLVM Integrated Tester) framework + +**Test Types:** +- `.ll` files: LLVM IR tests +- `.c/.cpp` files: Source-level tests (usually for Clang) +- Unit tests: C++ tests using Google Test framework + +**Running Specific Tests:** +```bash +# Run tests for a specific pass/analysis +llvm-lit llvm/test/Analysis/LoopInfo/ +llvm-lit llvm/test/Transforms/InstCombine/ + +# Run with specific flags +llvm-lit -v llvm/test/path/to/test.ll +llvm-lit --filter="NamePattern" test/directory/ +``` + +## Development Workflow + +**Common Patterns:** +- Most code follows LLVM coding standards (CamelCase for types, lowerCamelCase for variables) +- Use `LLVM_DEBUG()` macro for debug output +- Prefer LLVM data structures (SmallVector, DenseMap, etc.) over STL equivalents +- Use LLVM's error handling mechanisms (Expected<T>, Error, etc.) + +**Pass Development:** +- Analysis passes: Inherit from AnalysisInfoMixin or AnalysisPass +- Transformation passes: Inherit from PassInfoMixin or FunctionPass/ModulePass +- Register passes in the appropriate PassRegistry + +**Adding Tests:** +- Add regression tests to appropriate subdirectory in `llvm/test/` +- Use FileCheck for output verification +- Add unit tests to `llvm/unittests/` for complex logic +- Tests should be minimal and focused on specific functionality + +**Documentation:** +- Core docs in `llvm/docs/` (ReStructuredText format) +- Doxygen comments for public APIs +- Use `ninja docs-llvm-html` to build documentation + +## File Locations for Common Tasks + +**Analysis Pass Development:** +- Headers: `llvm/include/llvm/Analysis/` +- Implementation: `llvm/lib/Analysis/` +- Tests: `llvm/test/Analysis/PassName/` +- Unit tests: `llvm/unittests/Analysis/` + +**Transform Pass Development:** +- Headers: `llvm/include/llvm/Transforms/` +- Implementation: `llvm/lib/Transforms/` +- Tests: `llvm/test/Transforms/PassName/` + +**Target-Specific Code:** +- Headers: `llvm/include/llvm/Target/TargetName/` +- Implementation: `llvm/lib/Target/TargetName/` +- Tests: `llvm/test/CodeGen/TargetName/` + +**Tools:** +- Implementation: `llvm/tools/ToolName/` +- Tests: `llvm/test/tools/ToolName/` + +## LLDB-Specific Development + +**LLDB Structure:** +- **lldb/source/**: Core LLDB implementation +- **lldb/include/**: Public LLDB headers +- **lldb/test/**: Test suites (API, Shell tests) +- **lldb/tools/**: LLDB tools and utilities +- **lldb/unittests/**: Unit tests for LLDB components + +**LLDB Plugin Development:** +- **Language plugins**: `lldb/source/Plugins/Language/LanguageName/` +- **Type systems**: `lldb/source/Plugins/TypeSystem/` +- **Symbol files**: `lldb/source/Plugins/SymbolFile/` +- **Expression parsers**: `lldb/source/Plugins/ExpressionParser/` + +**LLDB Build Configuration for Development:** +```bash +# Minimal LLDB build for language plugin development +cmake -S llvm -B build -G Ninja \ + -DLLVM_ENABLE_PROJECTS="clang;lldb;flang" \ + -DLLVM_TARGETS_TO_BUILD="X86" \ + -DCMAKE_BUILD_TYPE=Debug \ + -DLLVM_ENABLE_ASSERTIONS=ON \ + -DLLDB_INCLUDE_TESTS=ON +``` + +**LLDB Testing:** +```bash +# Run all LLDB tests +ninja -C build check-lldb + +# Run LLDB API tests +ninja -C build check-lldb-api + +# Run LLDB unit tests +ninja -C build check-lldb-unit + +# Run specific LLDB test +llvm-lit lldb/test/API/lang/c/ +lldb-dotest lldb/test/API/functionalities/breakpoint/ +``` + +**Language Plugin Development Pattern:** +1. Create plugin directory: `lldb/source/Plugins/Language/LanguageName/` +2. Implement `LanguageName.h` and `LanguageName.cpp` inheriting from `Language` +3. Register plugin in `lldb/source/Plugins/Language/CMakeLists.txt` +4. Add plugin initialization in appropriate registry +5. Create tests in `lldb/test/API/lang/languagename/` + +**Key LLDB Classes for Language Plugins:** +- `Language`: Base class for language-specific functionality +- `TypeSystem`: Handles type representation and operations +- `FormatManager`: Manages data formatters for types +- `ExpressionParser`: Parses and evaluates expressions +- `DWARFASTParser`: Parses DWARF debug information into types + +**Fortran Development Workflow:** +- Use TDD: Write failing test first, implement to pass, refactor +- Build only LLDB components: `ninja -C build lldb lldb-test` +- Test frequently: `ninja -C build check-lldb-api-lang-fortran` +- Use selective building to save time on large codebase \ No newline at end of file diff --git a/LLDB_FORTRAN.md b/LLDB_FORTRAN.md new file mode 100644 index 0000000000000..83b528bb58022 --- /dev/null +++ b/LLDB_FORTRAN.md @@ -0,0 +1,210 @@ +# LLDB Fortran Language Support - Strategic Design Document + +## Project Overview + +This document outlines the strategic approach for implementing Fortran language support in LLDB (Issue #109119). The goal is to provide comprehensive debugging capabilities for Fortran programs, including variable inspection, expression evaluation, and Fortran-specific type support. + +## Current State Analysis + +### What Works Today +- Basic source-level debugging (step through lines, set breakpoints) +- DWARF debug information from Fortran compilers (gfortran, flang) contains rich metadata +- LLVM infrastructure already supports Fortran-specific DWARF tags and attributes + +### Current Limitations +- Warning: "This version of LLDB has no plugin for the language 'fortran08'" +- Limited variable inspection capabilities +- No Fortran-specific expression evaluation +- No understanding of Fortran-specific types (COMPLEX, CHARACTER, etc.) +- Different symbol naming conventions across compilers (MAIN__ vs _QQmain) + +## Technical Architecture + +### Core Components Required + +1. **Fortran Language Plugin** (`FortranLanguage` class) + - Inherit from `Language` base class + - Implement Fortran-specific language identification + - Handle case-insensitive identifiers + - Support multiple Fortran standards (77, 90, 95, 2003, 2008, 2018) + +2. **Fortran Type System Integration** + - COMPLEX type support (real and imaginary parts) + - CHARACTER type with length specifications + - Fortran array types with dimension information + - LOGICAL type mapping + - Derived type support + - Parameterized derived types (PDTs) + +3. **Expression Parser Enhancement** + - Fortran syntax support in expression evaluator + - Intrinsic function support (SIZE, SHAPE, LBOUND, UBOUND, etc.) + - Fortran operators (**, .EQ., .NE., etc.) + - Case-insensitive variable name resolution + +4. **Symbol Resolution** + - Handle compiler-specific name mangling (gfortran vs flang) + - Main program entry point identification + - Module and subprogram name resolution + - Common block variable handling + +### Plugin Architecture Integration + +Following the established pattern in LLDB: +``` +lldb/source/Plugins/Language/Fortran/ +├── CMakeLists.txt +├── FortranLanguage.h +├── FortranLanguage.cpp +├── FortranFormatters.h +├── FortranFormatters.cpp +└── FortranExpressionParser.h +``` + +### DWARF Integration Points + +Leverage existing Fortran-specific DWARF features: +- `DW_TAG_string_type` for CHARACTER variables +- `DW_AT_elemental`, `DW_AT_pure`, `DW_AT_recursive` for procedure attributes +- Fortran array type information +- Complex number representation + +## Implementation Strategy + +### Phase 1: Minimal Viable Plugin (MVP) +**Goal**: Eliminate the "no plugin" warning and basic functionality + +**Deliverables**: +- Basic `FortranLanguage` plugin registration +- Language type recognition for all Fortran standards +- Source file extension recognition (.f, .f90, .f95, .f03, .f08, .f18) +- Minimal test infrastructure + +**Testing Strategy**: +- Unit tests for language recognition +- Basic regression tests with simple Fortran programs +- CI integration with both gfortran and flang + +### Phase 2: Type System Foundation +**Goal**: Proper display of Fortran variables + +**Deliverables**: +- COMPLEX type formatter +- CHARACTER type formatter with length display +- LOGICAL type formatter +- Basic array display +- Enhanced DWARF parsing for Fortran types + +**Testing Strategy**: +- Type-specific test programs +- Variable inspection tests +- Memory layout verification + +### Phase 3: Expression Evaluation +**Goal**: Enable Fortran expression evaluation in debugger + +**Deliverables**: +- Fortran expression parser +- Basic intrinsic function support +- Case-insensitive identifier resolution +- Fortran operator support + +**Testing Strategy**: +- Expression evaluation test suite +- Intrinsic function tests +- Operator precedence tests + +### Phase 4: Advanced Features +**Goal**: Complete Fortran debugging experience + +**Deliverables**: +- Derived type support +- Module debugging +- Advanced array operations +- Fortran-specific exception handling +- Comprehensive documentation + +## Build System Integration + +### Selective Building Strategy +Given the massive LLVM codebase, we need a minimal build configuration: + +```bash +# Minimal LLDB build for Fortran development +cmake -S llvm -B build -G Ninja \ + -DLLVM_ENABLE_PROJECTS="clang;lldb;flang" \ + -DLLVM_TARGETS_TO_BUILD="X86" \ + -DCMAKE_BUILD_TYPE=Debug \ + -DLLVM_ENABLE_ASSERTIONS=ON \ + -DLLDB_INCLUDE_TESTS=ON +``` + +### Test-Driven Development Workflow +1. Write failing test for new functionality +2. Implement minimal code to pass test +3. Refactor and optimize +4. Ensure all existing tests still pass + +### Testing Infrastructure +- **Unit Tests**: `lldb/unittests/Language/Fortran/` +- **Integration Tests**: `lldb/test/API/lang/fortran/` +- **Lit Tests**: `lldb/test/Shell/lang/fortran/` + +## Risk Assessment & Mitigation + +### Technical Risks +1. **Compiler Divergence**: Different Fortran compilers (gfortran vs flang) may generate incompatible DWARF + - *Mitigation*: Test with both compilers, abstract common functionality + +2. **Complex Type System**: Fortran has unique features not present in C/C++ + - *Mitigation*: Phase implementation, start with basic types + +3. **Performance Impact**: Additional language support may slow down LLDB + - *Mitigation*: Profile performance, use lazy loading where possible + +### Project Risks +1. **Large Codebase**: LLVM/LLDB is enormous and complex + - *Mitigation*: Focus on minimal builds, selective testing + +2. **Community Integration**: Changes need upstream acceptance + - *Mitigation*: Engage with LLVM community early, follow contribution guidelines + +## Success Metrics + +### Short-term (Phase 1-2) +- No "unsupported language" warnings for Fortran files +- Basic variable inspection works for primitive types +- CI tests pass consistently + +### Medium-term (Phase 3) +- Expression evaluation works for simple Fortran expressions +- COMPLEX and CHARACTER types display correctly +- Arrays can be inspected element by element + +### Long-term (Phase 4) +- Full Fortran debugging feature parity with C/C++ +- Support for derived types and modules +- Community adoption and upstream integration + +## Dependencies + +### External Dependencies +- LLVM/Clang infrastructure (already present) +- DWARF standard support for Fortran +- Test Fortran compilers (gfortran, flang) + +### Internal Dependencies +- LLDB plugin architecture +- Expression evaluation framework +- Type system infrastructure +- Testing framework + +## Next Steps + +1. Set up minimal build configuration for rapid iteration +2. Create basic test infrastructure for Fortran +3. Implement Phase 1 MVP (basic plugin registration) +4. Establish CI pipeline with Fortran test cases +5. Begin Phase 2 implementation (type system) + +This strategic approach ensures incremental progress while maintaining code quality and test coverage throughout the development process. \ No newline at end of file >From 986a2f24ee359e5c4b35f9cc7bc8c06451464429 Mon Sep 17 00:00:00 2001 From: Christopher Albert <alb...@alumni.tugraz.at> Date: Sun, 27 Jul 2025 18:05:52 +0200 Subject: [PATCH 2/3] Plan for LLDB Fortran --- BACKLOG.md | 25 +++++++++++++++---------- CLAUDE.md | 32 ++++++++++++++++++++++++-------- LLDB_FORTRAN.md | 18 +++++++++++------- 3 files changed, 50 insertions(+), 25 deletions(-) diff --git a/BACKLOG.md b/BACKLOG.md index 17b06649bbff0..379f323ed7405 100644 --- a/BACKLOG.md +++ b/BACKLOG.md @@ -22,8 +22,9 @@ ### Story 1.2: Test Infrastructure Foundation - [ ] Set up basic test structure in `lldb/test/API/lang/fortran/` -- [ ] Create simple Fortran test programs (.f90 files) -- [ ] Establish lit test configuration +- [ ] Create simple Fortran test programs (.f90 files) with Makefile +- [ ] Add Python test classes inheriting from `lldbsuite.test.TestBase` +- [ ] Configure lit test discovery for Fortran API tests - [ ] Add CMake integration for Fortran tests **Acceptance Criteria**: @@ -55,23 +56,27 @@ ### Story 2.1: Plugin Registration Infrastructure (RED) - [ ] Create `lldb/source/Plugins/Language/Fortran/` directory structure -- [ ] Implement basic `FortranLanguage.h` class declaration -- [ ] Add plugin registration in PluginManager +- [ ] Implement basic `FortranLanguage.h` class declaration inheriting from `Language` +- [ ] Add `LLDB_PLUGIN_DEFINE(FortranLanguage)` macro +- [ ] Register plugin with PluginManager using standard pattern +- [ ] Add to `lldb/source/Plugins/Language/CMakeLists.txt` - [ ] Write failing test for language recognition **Acceptance Criteria**: - LLDB recognizes Fortran as a supported language - No "unsupported language" warnings for Fortran files - Plugin loads without errors +- Follows LLVM coding standards (C++17, proper includes, naming) **Test Cases (RED phase)**: ```python -# Test: test_fortran_language_recognition.py -def test_fortran_language_detected(self): - """Test that LLDB recognizes Fortran source files""" - # This should FAIL initially - self.expect("settings show target.language", - substrs=["fortran"]) +# Test: test_fortran_language_recognition.py (in lldb/test/API/lang/fortran/) +class FortranLanguageTestCase(TestBase): + def test_fortran_language_detected(self): + """Test that LLDB recognizes Fortran source files""" + # This should FAIL initially + self.expect("settings show target.language", + substrs=["fortran"]) ``` ### Story 2.2: Language Type Recognition (GREEN) diff --git a/CLAUDE.md b/CLAUDE.md index a5b056426e32d..d358aee0d16f6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -170,13 +170,18 @@ llvm-lit --filter="NamePattern" test/directory/ **LLDB Build Configuration for Development:** ```bash -# Minimal LLDB build for language plugin development +# Recommended LLDB build for language plugin development cmake -S llvm -B build -G Ninja \ -DLLVM_ENABLE_PROJECTS="clang;lldb;flang" \ -DLLVM_TARGETS_TO_BUILD="X86" \ - -DCMAKE_BUILD_TYPE=Debug \ + -DCMAKE_BUILD_TYPE=RelWithDebInfo \ -DLLVM_ENABLE_ASSERTIONS=ON \ - -DLLDB_INCLUDE_TESTS=ON + -DLLDB_INCLUDE_TESTS=ON \ + -DLLVM_INSTALL_UTILS=ON \ + -DLLVM_USE_LINKER=lld + +# For debugging LLDB itself, use Debug instead of RelWithDebInfo +# cmake -S llvm -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug ... ``` **LLDB Testing:** @@ -198,9 +203,11 @@ lldb-dotest lldb/test/API/functionalities/breakpoint/ **Language Plugin Development Pattern:** 1. Create plugin directory: `lldb/source/Plugins/Language/LanguageName/` 2. Implement `LanguageName.h` and `LanguageName.cpp` inheriting from `Language` -3. Register plugin in `lldb/source/Plugins/Language/CMakeLists.txt` -4. Add plugin initialization in appropriate registry -5. Create tests in `lldb/test/API/lang/languagename/` +3. Use `LLDB_PLUGIN_DEFINE(LanguageName)` macro for plugin definition +4. Register with PluginManager in Initialize/Terminate methods +5. Add to `lldb/source/Plugins/Language/CMakeLists.txt` using `add_subdirectory()` +6. Create tests in `lldb/test/API/lang/languagename/` with proper Python test classes +7. Follow LLVM coding standards: C++17, CamelCase types, lowerCamelCase variables **Key LLDB Classes for Language Plugins:** - `Language`: Base class for language-specific functionality @@ -212,5 +219,14 @@ lldb-dotest lldb/test/API/functionalities/breakpoint/ **Fortran Development Workflow:** - Use TDD: Write failing test first, implement to pass, refactor - Build only LLDB components: `ninja -C build lldb lldb-test` -- Test frequently: `ninja -C build check-lldb-api-lang-fortran` -- Use selective building to save time on large codebase \ No newline at end of file +- Test frequently: `llvm-lit lldb/test/API/lang/fortran/` +- Format code: `git clang-format HEAD~1` before committing +- Follow LLVM conventions: single commit per PR, no unrelated changes +- Use selective building to save time on large codebase + +**LLVM Contribution Guidelines:** +- Base patches on recent `main` branch commit +- Include test cases with all patches +- Format code with clang-format +- Follow C++17 standards and LLVM data structures (SmallVector, DenseMap) +- Use LLVM error handling (Expected<T>, Error) over exceptions \ No newline at end of file diff --git a/LLDB_FORTRAN.md b/LLDB_FORTRAN.md index 83b528bb58022..42050084f70c0 100644 --- a/LLDB_FORTRAN.md +++ b/LLDB_FORTRAN.md @@ -56,11 +56,11 @@ lldb/source/Plugins/Language/Fortran/ ├── CMakeLists.txt ├── FortranLanguage.h ├── FortranLanguage.cpp -├── FortranFormatters.h -├── FortranFormatters.cpp -└── FortranExpressionParser.h +└── FortranFormatters.cpp ``` +**Plugin Registration**: Use `LLDB_PLUGIN_DEFINE(FortranLanguage)` macro and register with PluginManager following the pattern from CPlusPlusLanguage and ObjCLanguage. + ### DWARF Integration Points Leverage existing Fortran-specific DWARF features: @@ -127,18 +127,22 @@ Leverage existing Fortran-specific DWARF features: ## Build System Integration ### Selective Building Strategy -Given the massive LLVM codebase, we need a minimal build configuration: +Following LLVM best practices for focused development: ```bash -# Minimal LLDB build for Fortran development +# Recommended LLDB build for Fortran development cmake -S llvm -B build -G Ninja \ -DLLVM_ENABLE_PROJECTS="clang;lldb;flang" \ -DLLVM_TARGETS_TO_BUILD="X86" \ - -DCMAKE_BUILD_TYPE=Debug \ + -DCMAKE_BUILD_TYPE=RelWithDebInfo \ -DLLVM_ENABLE_ASSERTIONS=ON \ - -DLLDB_INCLUDE_TESTS=ON + -DLLDB_INCLUDE_TESTS=ON \ + -DLLVM_INSTALL_UTILS=ON \ + -DLLVM_USE_LINKER=lld ``` +**Note**: Using `RelWithDebInfo` provides better performance than `Debug` while maintaining debug symbols. Use `Debug` only when debugging LLDB itself. + ### Test-Driven Development Workflow 1. Write failing test for new functionality 2. Implement minimal code to pass test >From 73aaacdeb5ba5d3d214ae57a4e8f88c1aa40d4dc Mon Sep 17 00:00:00 2001 From: Christopher Albert <alb...@alumni.tugraz.at> Date: Sun, 27 Jul 2025 18:21:30 +0200 Subject: [PATCH 3/3] Add Fortran LLDB development configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create configure-lldb-fortran.sh script for optimal build setup - Add LLDBConfigFortran.cmake module for Fortran-specific configuration - Integrate Fortran configuration into main LLDB CMake build - Update BACKLOG.md to reflect completed task This establishes the foundation for efficient LLDB Fortran development with minimal build times and proper test infrastructure support. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <nore...@anthropic.com> --- BACKLOG.md | 2 +- configure-lldb-fortran.sh | 28 +++++++++++ lldb/CMakeLists.txt | 1 + lldb/cmake/modules/LLDBConfigFortran.cmake | 56 ++++++++++++++++++++++ 4 files changed, 86 insertions(+), 1 deletion(-) create mode 100755 configure-lldb-fortran.sh create mode 100644 lldb/cmake/modules/LLDBConfigFortran.cmake diff --git a/BACKLOG.md b/BACKLOG.md index 379f323ed7405..8970572f81947 100644 --- a/BACKLOG.md +++ b/BACKLOG.md @@ -5,7 +5,7 @@ **Goal**: Establish efficient development and testing environment ### Story 1.1: Minimal Build Configuration -- [ ] Create optimal CMake configuration for Fortran LLDB development +- [x] Create optimal CMake configuration for Fortran LLDB development - [ ] Document build time and disk space requirements - [ ] Verify build works with both Debug and Release configurations - [ ] Test with different generators (Ninja, Make) diff --git a/configure-lldb-fortran.sh b/configure-lldb-fortran.sh new file mode 100755 index 0000000000000..d0235281a31af --- /dev/null +++ b/configure-lldb-fortran.sh @@ -0,0 +1,28 @@ +#!/bin/bash +# Optimal build configuration for LLDB Fortran development +# This script creates a minimal build with only necessary components + +BUILD_DIR="${1:-build-fortran}" +BUILD_TYPE="${2:-RelWithDebInfo}" + +echo "Configuring LLVM/LLDB for Fortran development..." +echo "Build directory: $BUILD_DIR" +echo "Build type: $BUILD_TYPE" + +cmake -S llvm -B "$BUILD_DIR" -G Ninja \ + -DLLVM_ENABLE_PROJECTS="clang;lldb;flang" \ + -DLLVM_TARGETS_TO_BUILD="X86" \ + -DCMAKE_BUILD_TYPE="$BUILD_TYPE" \ + -DLLVM_ENABLE_ASSERTIONS=ON \ + -DLLDB_INCLUDE_TESTS=ON \ + -DLLVM_INSTALL_UTILS=ON \ + -DLLVM_USE_LINKER=lld \ + -DLLVM_PARALLEL_LINK_JOBS=2 \ + -DLLVM_PARALLEL_COMPILE_JOBS=6 \ + -DLLDB_TEST_FORTRAN=ON \ + -DCMAKE_EXPORT_COMPILE_COMMANDS=ON + +echo "Configuration complete. To build:" +echo " ninja -C $BUILD_DIR lldb lldb-test" +echo "To run Fortran tests:" +echo " ninja -C $BUILD_DIR check-lldb-lang-fortran" \ No newline at end of file diff --git a/lldb/CMakeLists.txt b/lldb/CMakeLists.txt index e3b72e94d4beb..9937895ff5a97 100644 --- a/lldb/CMakeLists.txt +++ b/lldb/CMakeLists.txt @@ -38,6 +38,7 @@ endif() include(LLDBConfig) include(AddLLDB) include(LLDBLayeringCheck) +include(LLDBConfigFortran) set(LLDB_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/include) diff --git a/lldb/cmake/modules/LLDBConfigFortran.cmake b/lldb/cmake/modules/LLDBConfigFortran.cmake new file mode 100644 index 0000000000000..7b8855dc39c4f --- /dev/null +++ b/lldb/cmake/modules/LLDBConfigFortran.cmake @@ -0,0 +1,56 @@ +# LLDB Fortran Support Configuration +# This module handles configuration specific to Fortran language support in LLDB + +# Option to enable Fortran support testing +option(LLDB_TEST_FORTRAN "Enable Fortran language tests" ON) + +# Find Fortran compiler for testing +if(LLDB_TEST_FORTRAN) + include(CheckLanguage) + check_language(Fortran) + + if(CMAKE_Fortran_COMPILER) + enable_language(Fortran) + message(STATUS "Found Fortran compiler: ${CMAKE_Fortran_COMPILER}") + + # Check if it's gfortran or flang + execute_process( + COMMAND ${CMAKE_Fortran_COMPILER} --version + OUTPUT_VARIABLE FORTRAN_COMPILER_VERSION + ERROR_QUIET + ) + + if(FORTRAN_COMPILER_VERSION MATCHES "GNU Fortran") + set(LLDB_TEST_FORTRAN_COMPILER "gfortran") + elseif(FORTRAN_COMPILER_VERSION MATCHES "flang") + set(LLDB_TEST_FORTRAN_COMPILER "flang") + else() + set(LLDB_TEST_FORTRAN_COMPILER "unknown") + endif() + + message(STATUS "Fortran compiler type: ${LLDB_TEST_FORTRAN_COMPILER}") + else() + message(WARNING "No Fortran compiler found. Fortran tests will be disabled.") + set(LLDB_TEST_FORTRAN OFF) + endif() +endif() + +# Export variables for use in test configuration +set(LLDB_TEST_FORTRAN ${LLDB_TEST_FORTRAN} PARENT_SCOPE) +set(LLDB_TEST_FORTRAN_COMPILER ${LLDB_TEST_FORTRAN_COMPILER} PARENT_SCOPE) + +# Add Fortran test directory if enabled +if(LLDB_TEST_FORTRAN) + list(APPEND LLDB_TEST_DEPS lldb-test) + + # Add custom target for Fortran tests only + add_custom_target(check-lldb-lang-fortran + COMMAND ${CMAKE_COMMAND} -E echo "Running LLDB Fortran language tests..." + COMMAND ${Python3_EXECUTABLE} ${LLVM_MAIN_SRC_DIR}/llvm/utils/lit/lit.py + --param lldb_site_config=${CMAKE_CURRENT_BINARY_DIR}/test/lit.site.cfg.py + ${CMAKE_CURRENT_SOURCE_DIR}/test/API/lang/fortran/ + DEPENDS ${LLDB_TEST_DEPS} + COMMENT "Running LLDB Fortran language tests" + USES_TERMINAL + ) +endif() \ No newline at end of file _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
