diff --git a/.github/dule-test.prompt.md b/.claude/commands/add_dual_test_case.md similarity index 99% rename from .github/dule-test.prompt.md rename to .claude/commands/add_dual_test_case.md index e947472d5..da95eb851 100644 --- a/.github/dule-test.prompt.md +++ b/.claude/commands/add_dual_test_case.md @@ -1,4 +1,4 @@ -# OpenSwiftUI Copilot Test Authoring Rules +# OpenSwiftUI DualTests Rules This file documents precise rules and templates for writing Tests and DualTests used across the OpenSwiftUI repository. Follow these rules exactly when generating new test cases. diff --git a/.github/format.prompt.md b/.claude/commands/format_swiftinterface.md similarity index 100% rename from .github/format.prompt.md rename to .claude/commands/format_swiftinterface.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 3d6736320..000000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,192 +0,0 @@ -# OpenSwiftUI Copilot Instructions - -This file contains coding guidelines and conventions for AI assistants working on the OpenSwiftUI project. - -## Quick Reference - -### Key Principles -- Use `swift-testing` framework with `#expect` macro (not XCTest) -- Use `package` access level for cross-module APIs -- Follow SwiftUI API compatibility patterns -- Trim trailing whitespaces automatically -- Use 4-space indentation consistently - -## Testing Guidelines - -### Testing Framework - -- Use the `swift-testing` framework with the `#expect` macro for all test assertions -- Import testing framework with: `import Testing` -- Do NOT use XCTest framework unless specifically required for compatibility - -### Test Structure - -```swift -import Testing - -struct DemoTests { - @Test - func functionality() { - let value = SomeType() - - #expect(value.property == expectedValue) - #expect(value.method() == expectedResult) - } - - @Test - func errorConditions() { - #expect(throws: SomeError.self) { - try riskyOperation() - } - } -} -``` - -### Test Conventions - -- **Do NOT write any comments in test case body** - keep test code clean and self-explanatory -- Use descriptive test function names that clearly indicate what is being tested -- Group related tests using `// MARK: -` sections -- Use `#expect` for all assertions instead of XCTest assertions -- Prefer multiple focused tests over one large test -- Do not add test prefix to test function names (e.g., `testFunctionality` should be `functionality`) -- Use `@Test` attribute for test functions - -## Code Organization - -### File Structure -- Use `// MARK: -` to separate different topics and sections within files -- Organize code logically with clear separation of concerns -- Place imports at the top, followed by type definitions, then implementations - -### Example MARK Usage -```swift -// MARK: - A - -... - -// MARK: - B - -... - -// MARK: - C - -... -``` - -## Swift Coding Style - -### Access Control Hierarchy - -1. `public` - External API surface -2. `package` - Cross-module internal APIs -3. `internal` - Module-internal APIs (default) -4. `private` - Implementation details - -### Naming Conventions - -- Follow Swift API Design Guidelines -- Use descriptive names that clearly indicate purpose -- Prefer full words over abbreviations -- Use camelCase for variables, functions, and properties -- Use PascalCase for types, protocols, and cases -- Prefix internal types with `_` when they mirror SwiftUI internals - -### Code Formatting Rules - -- **Automatically trim trailing whitespaces including whitespace-only lines** -- Use consistent indentation (4 spaces, not tabs) -- Place opening braces on the same line as the declaration -- Use proper spacing around operators and after commas -- Align code vertically when it improves readability -- Maximum line length: 120 characters (soft limit) - -### Type Definitions - -```swift -struct SomeType { - let property: String - - private let internalProperty: Int - - func method() -> String { - // Implementation - } -} -``` - -## Architecture Patterns - -### SwiftUI Compatibility -- Maintain API compatibility with SwiftUI when implementing equivalent functionality -- Use similar naming conventions and parameter patterns as SwiftUI -- Implement protocols and extensions that mirror SwiftUI's design - -### Module Organization -- Keep related functionality in appropriate modules -- Use clear module boundaries -- Avoid circular dependencies between modules - -### Error Handling -- Use Swift's error handling mechanisms (`throws`, `Result`, etc.) -- Provide meaningful error messages -- Handle errors gracefully at appropriate levels - -## Documentation - -### Code Comments -- Write clear, concise comments for complex logic -- Use documentation comments (`///`) for APIs documentation -- Avoid obvious comments that don't add value -- Keep comments up-to-date with code changes - -### API Documentation -```swift -/// A brief description of what this function does. -/// -/// - Parameter value: Description of the parameter -/// - Returns: Description of the return value -/// - Throws: Description of potential errors -func someFunction(value: String) throws -> Int { - // Implementation -} -``` - -## Performance Considerations - -- Prefer value types (structs) over reference types (classes) when appropriate -- Use lazy initialization for expensive computations -- Consider memory management and avoid retain cycles -- Optimize for common use cases while maintaining flexibility - -## Dependencies and Imports - -- Minimize external dependencies -- Use conditional compilation for platform-specific code -- Import only what is needed (avoid importing entire modules when specific types suffice) -- Organize imports alphabetically within groups (system frameworks first, then project modules) - -## Version Control - -- Make atomic commits with clear, descriptive messages -- Keep changes focused and reviewable -- Follow the project's branching strategy -- Ensure all tests pass before committing - -## Platform Compatibility - -- Support multiple Apple platforms (iOS, macOS, watchOS, tvOS, visionOS) -- Use availability annotations when using platform-specific APIs -- Test on supported platform versions -- Use feature detection rather than version checking when possible - ---- - -## Troubleshooting - -### Common Issues -- **Build errors**: Check `package` vs `internal` access levels -- **Test failures**: Ensure using `#expect` not XCTest assertions -- **SwiftUI compatibility**: Verify API signatures match exactly - -Remember: This project aims to provide a compatible alternative to SwiftUI, so maintain consistency with SwiftUI's patterns and conventions while following these OpenSwiftUI-specific guidelines. \ No newline at end of file diff --git a/.gitignore b/.gitignore index 43e4312c6..c6df7f808 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,7 @@ Example/Example.xcodeproj/xcshareddata __Snapshots__ Example/ReferenceImages/**/*.png -.claude +.claude/* +!.claude/commands/ .docs gh-pages diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..f9acd0eeb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,103 @@ +# AGENTS.md + +This file provides guidance to AI agents when working with code in this repository. + +## Project Overview + +OpenSwiftUI is an open source implementation of Apple's SwiftUI framework, designed to: +- Build GUI apps on non-Apple platforms (Linux, Windows) +- Diagnose and debug SwiftUI issues on Apple platforms +- Maintain API compatibility with SwiftUI + +This project is in active development and contains multiple Swift packages with extensive environment-based configuration. + +## Build Commands + +### Standard Build +```bash +./Scripts/build.sh +# Or directly: swift build +``` + +### Build with Library Evolution +```bash +./Scripts/build_swiftinterface.sh +# Generates module interfaces for library evolution +``` + +### Environment Variables +The build system uses many environment variables for configuration: +- `OPENSWIFTUI_BUILD_FOR_DARWIN_PLATFORM`: Build for Darwin platforms (default: true on macOS) +- `OPENSWIFTUI_DEVELOPMENT`: Enable development mode features +- `OPENSWIFTUI_USE_LOCAL_DEPS`: Use local dependency paths instead of remote repos +- `OPENSWIFTUI_LIBRARY_EVOLUTION`: Enable library evolution support +- `OPENSWIFTUI_COMPATIBILITY_TEST`: Run compatibility tests with SwiftUI + +## Test Commands + +### Run All Tests +```bash +swift test +``` + +### Run Specific Test Target +```bash +swift test --filter OpenSwiftUICoreTests +swift test --filter OpenSwiftUICompatibilityTests +swift test --filter OpenSwiftUISymbolDualTests +``` + +### Test with Coverage +```bash +swift test --enable-code-coverage +``` + +### List Available Tests +```bash +swift test --list-tests +``` + +## Dependencies Setup + +The project requires cloning additional repositories in the same parent directory: + +```bash +cd .. +git clone https://github.com/OpenSwiftUIProject/OpenAttributeGraph.git +git clone https://github.com/OpenSwiftUIProject/OpenRenderBox.git +git clone https://github.com/OpenSwiftUIProject/DarwinPrivateFrameworks.git +``` + +## Architecture + +### Core Modules + +1. **OpenSwiftUI_SPI**: System Programming Interface and low-level utilities +2. **OpenSwiftUICore**: Core framework implementation with animations, layout, graphics + +-------------------------------------------------------------------------------- +## Documentation + +Use swift-docc format when writing documentation. + +Follow SwiftUI documentation style. + +Since CDDefaultCodeListingLanguage is Swift, stop using ```swift and ``` to wrap Swift code example in documentation. Instead just use a new line + 4 space indent. + +Example: + +``` + /// Example code: + /// + /// @main + /// struct MyApp: App { + /// var body: some View { + /// WindowGroup { + /// ContentView() + /// } + /// .environment(ProfileService.currentProfile) + /// } + /// } + /// + public protocol App {} +``` \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index bff8a3dac..000000000 --- a/CLAUDE.md +++ /dev/null @@ -1,156 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -OpenSwiftUI is an open source implementation of Apple's SwiftUI framework, designed to: -- Build GUI apps on non-Apple platforms (Linux, Windows) -- Diagnose and debug SwiftUI issues on Apple platforms -- Maintain API compatibility with SwiftUI - -This project is in active development and contains multiple Swift packages with extensive environment-based configuration. - -## Build Commands - -### Standard Build -```bash -./Scripts/build.sh -# Or directly: swift build -``` - -### Build with Library Evolution -```bash -./Scripts/build_swiftinterface.sh -# Generates module interfaces for library evolution -``` - -### Environment Variables -The build system uses many environment variables for configuration: -- `OPENSWIFTUI_BUILD_FOR_DARWIN_PLATFORM`: Build for Darwin platforms (default: true on macOS) -- `OPENSWIFTUI_DEVELOPMENT`: Enable development mode features -- `OPENSWIFTUI_USE_LOCAL_DEPS`: Use local dependency paths instead of remote repos -- `OPENSWIFTUI_LIBRARY_EVOLUTION`: Enable library evolution support -- `OPENSWIFTUI_COMPATIBILITY_TEST`: Run compatibility tests with SwiftUI - -## Test Commands - -### Run All Tests -```bash -swift test -``` - -### Run Specific Test Target -```bash -swift test --filter OpenSwiftUICoreTests -swift test --filter OpenSwiftUICompatibilityTests -swift test --filter OpenSwiftUISymbolDualTests -``` - -### Test with Coverage -```bash -swift test --enable-code-coverage -``` - -### List Available Tests -```bash -swift test --list-tests -``` - -## Dependencies Setup - -The project requires cloning additional repositories in the same parent directory: - -```bash -cd .. -git clone https://github.com/OpenSwiftUIProject/OpenAttributeGraph.git -git clone https://github.com/OpenSwiftUIProject/OpenRenderBox.git -git clone https://github.com/OpenSwiftUIProject/DarwinPrivateFrameworks.git -``` - -## Architecture - -### Core Modules - -1. **OpenSwiftUI_SPI**: System Programming Interface and low-level utilities -2. **OpenSwiftUICore**: Core framework implementation with animations, layout, graphics -3. **OpenSwiftUI**: Main public API layer, SwiftUI-compatible interface -4. **OpenSwiftUIExtension**: Additional APIs extending OpenSwiftUI/SwiftUI -5. **OpenSwiftUIBridge**: Bridge layer for migrating from other frameworks - -### Key Source Directories - -- `Sources/OpenSwiftUICore/`: Core implementation (Animation, Layout, Graphics, etc.) -- `Sources/OpenSwiftUI/`: Public API layer matching SwiftUI -- `Sources/OpenSwiftUI_SPI/`: Low-level system interfaces and utilities -- `Sources/COpenSwiftUI/`: C/Objective-C interop code -- `Tests/`: Comprehensive test suites for all modules -- `Example/`: Demo applications and UI tests - -### Testing Framework - -The project uses **swift-testing framework** (not XCTest): -- Import with `import Testing` -- Use `@Test` attribute for test functions -- Use `#expect()` for assertions instead of XCTest assertions -- No comments in test case bodies - keep tests clean and self-explanatory -- For floating-point comparisons, use `isApproximatelyEqual` instead of `==` to handle precision issues: - ```swift - #expect(value.isApproximatelyEqual(to: expectedValue)) - ``` - -**Exception: Macro Tests** -- Macro tests must use **XCTest** framework (not swift-testing) -- Import with `import XCTest` -- Use `final class TestName: XCTestCase` with `func testName()` methods -- Use XCTest assertions like `XCTAssertEqual()`, `XCTAssertTrue()`, etc. -- For macro expansion testing, use `assertMacroExpansion` from `SwiftSyntaxMacrosTestSupport` - -### Compatibility Tests - -When writing tests in `OpenSwiftUICompatibilityTests`: -- **DO NOT add conditional imports** - imports are handled in `Export.swift` -- **NEVER use module-qualified types** (e.g., `SwiftUI.PeriodicTimelineSchedule`) -- Write test code that works identically with both SwiftUI and OpenSwiftUI -- Simply use types directly without any module prefixes: - ```swift - // No conditional imports needed - Export.swift handles this - let schedule = PeriodicTimelineSchedule(from: startDate, by: interval) - let entries = schedule.entries(from: queryDate, mode: .normal) - ``` - -### Code Style (from .github/copilot-instructions.md) - -- Use `package` access level for cross-module APIs -- 4-space indentation, trim trailing whitespaces -- Use `// MARK: -` to separate code sections -- Maximum line length: 120 characters (soft limit) -- Follow SwiftUI API compatibility patterns -- Prefix internal types with `_` when mirroring SwiftUI internals - -### Platform Support - -- **Darwin Platforms**: Currently only iOS and macOS are supported -- **Linux**: Build and test support, some features limited -- **Windows**: Not yet supported - -### Development Configurations - -For the Example app: -- `SwiftUIDebug`: Run with Apple's SwiftUI -- `OpenSwiftUIDebug`: Run with OpenSwiftUI implementation - -## Environment Configuration - -The Package.swift heavily uses environment variables for conditional compilation: -- Most features are platform-dependent (Darwin vs non-Darwin) -- Development mode enables additional debugging features -- Library evolution mode generates .swiftinterface files -- Various private framework integrations can be toggled - -## Important Notes - -- This project uses private Apple APIs and frameworks - NOT for App Store distribution -- SwiftUI compatibility is the primary goal - match Apple's API signatures exactly -- The project requires Swift 6.1.2+ and specific platform versions -- Cross-platform support relies on custom implementations of Apple frameworks \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 000000000..55bf822df --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +./AGENTS.md \ No newline at end of file