diff --git a/DETAILS.md b/DETAILS.md new file mode 100644 index 00000000..3f55f7a9 --- /dev/null +++ b/DETAILS.md @@ -0,0 +1,334 @@ +# DETAILS.md + +πŸ” **Powered by [Detailer](https://detailer.ginylil.com)** - AI-first repository insights + + + +--- + +## 1. Project Overview + +### Purpose & Domain +This project is a **declarative Xcode project generator and build configuration system**, primarily implemented in Swift. It enables usersβ€”primarily iOS/macOS/tvOS/watchOS/visionOS developers and build engineersβ€”to define complex multi-platform Xcode projects, targets, schemes, dependencies, and build settings via YAML/JSON configuration files. The system automates the generation of `.xcodeproj` files, supporting modular, scalable, and reproducible project setups. + +### Problem Solved +- Eliminates manual Xcode project file editing, reducing human error and merge conflicts. +- Supports multi-platform Apple ecosystem projects with complex dependencies. +- Provides a flexible, extensible configuration schema for build settings, schemes, and targets. +- Facilitates integration with dependency managers (Carthage, Swift Package Manager). +- Enables automated testing, validation, and caching of project specs. +- Supports extensions (AppIntents, EndpointSecurity, Network Extensions, iMessage Extensions, etc.) and system-level components (DriverKit). + +### Target Users & Use Cases +- iOS/macOS/tvOS/watchOS/visionOS app developers managing complex multi-target projects. +- Build engineers automating project generation in CI/CD pipelines. +- Teams requiring consistent, version-controlled project configurations. +- Developers integrating external dependencies and custom build scripts. +- Extension developers needing specialized build configurations. + +### Core Business Logic & Domain Models +- **Project Specification Models:** `Project`, `Target`, `Scheme`, `Dependency`, `BuildSettings`, `Config`, `AggregateTarget`, etc. +- **Build Configuration:** Declarative YAML/JSON schemas defining targets, build phases, scripts, and settings. +- **Project Generation:** Translating specs into Xcode project files (`.xcodeproj`) using `XcodeProj` library. +- **Validation & Testing:** Ensuring configuration correctness via validation layers and extensive test fixtures. +- **CLI Tooling:** Command-line interface (`xcodegen`) for generating projects, dumping specs, and managing caches. + +--- + +## 2. Architecture and Structure + +### High-Level Architecture +- **Configuration Layer:** YAML/JSON files under `Tests/Fixtures/`, `SettingPresets/` define build settings, platforms, products, and supported destinations. +- **Model Layer:** Swift structs and enums in `Sources/ProjectSpec/` model project specs, targets, schemes, dependencies, and build settings. +- **Generation Layer:** `Sources/XcodeGenKit/` contains generators (`ProjectGenerator`, `PBXProjGenerator`, `SchemeGenerator`, `SourceGenerator`) that convert models into Xcode project files. +- **Core Utilities:** `Sources/XcodeGenCore/` provides utilities for concurrency, globbing, hashing, path manipulation, and string diffing. +- **CLI Layer:** `Sources/XcodeGenCLI/` implements the command-line interface, commands, argument parsing, and error handling. +- **Testing Layer:** `Tests/` contains unit, integration, and performance tests, with extensive fixtures and validation tests. +- **Scripts:** `scripts/` directory contains build automation and packaging scripts. + +### Complete Repository Structure (Key Files & Directories) + +``` +. +β”œβ”€β”€ .github/ +β”‚ └── workflows/ci.yml +β”œβ”€β”€ Assets/ +β”‚ └── Logo_animated.gif +β”œβ”€β”€ Docs/ +β”‚ β”œβ”€β”€ Examples.md +β”‚ β”œβ”€β”€ FAQ.md +β”‚ β”œβ”€β”€ ProjectSpec.md +β”‚ └── Usage.md +β”œβ”€β”€ SettingPresets/ +β”‚ β”œβ”€β”€ Configs/ +β”‚ β”‚ β”œβ”€β”€ debug.yml +β”‚ β”‚ └── release.yml +β”‚ β”œβ”€β”€ Platforms/ +β”‚ β”‚ β”œβ”€β”€ iOS.yml +β”‚ β”‚ β”œβ”€β”€ macOS.yml +β”‚ β”‚ β”œβ”€β”€ tvOS.yml +β”‚ β”‚ β”œβ”€β”€ visionOS.yml +β”‚ β”‚ └── watchOS.yml +β”‚ β”œβ”€β”€ Product_Platform/ +β”‚ β”‚ β”œβ”€β”€ application_iOS.yml +β”‚ β”‚ β”œβ”€β”€ application_macOS.yml +β”‚ β”‚ β”œβ”€β”€ application_tvOS.yml +β”‚ β”‚ β”œβ”€β”€ application_visionOS.yml +β”‚ β”‚ β”œβ”€β”€ application_watchOS.yml +β”‚ β”‚ └── bundle.unit-test_macOS.yml +β”‚ β”œβ”€β”€ Products/ +β”‚ β”‚ β”œβ”€β”€ framework.yml +β”‚ β”‚ β”œβ”€β”€ library.static.yml +β”‚ β”‚ β”œβ”€β”€ tv-app-extension.yml +β”‚ β”‚ └── watchkit2-extension.yml +β”‚ β”œβ”€β”€ SupportedDestinations/ +β”‚ β”‚ β”œβ”€β”€ iOS.yml +β”‚ β”‚ β”œβ”€β”€ macCatalyst.yml +β”‚ β”‚ β”œβ”€β”€ macOS.yml +β”‚ β”‚ β”œβ”€β”€ tvOS.yml +β”‚ β”‚ β”œβ”€β”€ visionOS.yml +β”‚ β”‚ └── watchOS.yml +β”‚ └── base.yml +β”œβ”€β”€ Sources/ +β”‚ β”œβ”€β”€ ProjectSpec/ +β”‚ β”‚ β”œβ”€β”€ AggregateTarget.swift +β”‚ β”‚ β”œβ”€β”€ BuildPhaseSpec.swift +β”‚ β”‚ β”œβ”€β”€ BuildRule.swift +β”‚ β”‚ β”œβ”€β”€ BuildScript.swift +β”‚ β”‚ β”œβ”€β”€ BuildSettingsExtractor.swift +β”‚ β”‚ β”œβ”€β”€ BuildToolPlugin.swift +β”‚ β”‚ β”œβ”€β”€ CacheFile.swift +β”‚ β”‚ β”œβ”€β”€ Config.swift +β”‚ β”‚ β”œβ”€β”€ Dependency.swift +β”‚ β”‚ β”œβ”€β”€ DeploymentTarget.swift +β”‚ β”‚ β”œβ”€β”€ FileType.swift +β”‚ β”‚ β”œβ”€β”€ GroupOrdering.swift +β”‚ β”‚ β”œβ”€β”€ Linkage.swift +β”‚ β”‚ β”œβ”€β”€ Platform.swift +β”‚ β”‚ β”œβ”€β”€ Project.swift +β”‚ β”‚ β”œβ”€β”€ Scheme.swift +β”‚ β”‚ β”œβ”€β”€ SpecFile.swift +β”‚ β”‚ β”œβ”€β”€ SpecValidation.swift +β”‚ β”‚ β”œβ”€β”€ Target.swift +β”‚ β”‚ β”œβ”€β”€ TargetScheme.swift +β”‚ β”‚ β”œβ”€β”€ TestPlan.swift +β”‚ β”‚ β”œβ”€β”€ TestableTargetReference.swift +β”‚ β”‚ β”œβ”€β”€ Version.swift +β”‚ β”‚ └── Yaml.swift +β”‚ β”œβ”€β”€ TestSupport/ +β”‚ β”‚ └── TestHelpers.swift +β”‚ β”œβ”€β”€ XcodeGen/ +β”‚ β”‚ └── main.swift +β”‚ β”œβ”€β”€ XcodeGenCLI/ +β”‚ β”‚ β”œβ”€β”€ Commands/ +β”‚ β”‚ β”‚ β”œβ”€β”€ CacheCommand.swift +β”‚ β”‚ β”‚ β”œβ”€β”€ DumpCommand.swift +β”‚ β”‚ β”‚ β”œβ”€β”€ GenerateCommand.swift +β”‚ β”‚ β”‚ └── ProjectCommand.swift +β”‚ β”‚ β”œβ”€β”€ Arguments.swift +β”‚ β”‚ β”œβ”€β”€ GenerationError.swift +β”‚ β”‚ └── XcodeGenCLI.swift +β”‚ β”œβ”€β”€ XcodeGenCore/ +β”‚ β”‚ β”œβ”€β”€ ArrayExtensions.swift +β”‚ β”‚ β”œβ”€β”€ Atomic.swift +β”‚ β”‚ β”œβ”€β”€ Glob.swift +β”‚ β”‚ β”œβ”€β”€ MD5.swift +β”‚ β”‚ β”œβ”€β”€ PathExtensions.swift +β”‚ β”‚ └── StringDiff.swift +β”‚ └── XcodeGenKit/ +β”‚ β”œβ”€β”€ BreakpointGenerator.swift +β”‚ β”œβ”€β”€ CarthageDependencyResolver.swift +β”‚ β”œβ”€β”€ CarthageVersionLoader.swift +β”‚ β”œβ”€β”€ FileWriter.swift +β”‚ β”œβ”€β”€ InfoPlistGenerator.swift +β”‚ β”œβ”€β”€ PBXProjGenerator.swift +β”‚ β”œβ”€β”€ ProjectGenerator.swift +β”‚ β”œβ”€β”€ SchemeGenerator.swift +β”‚ β”œβ”€β”€ SettingsBuilder.swift +β”‚ β”œβ”€β”€ SourceGenerator.swift +β”‚ β”œβ”€β”€ StringCatalogDecoding.swift +β”‚ β”œβ”€β”€ Version.swift +β”‚ └── XCProjExtensions.swift +β”œβ”€β”€ Tests/ +β”‚ β”œβ”€β”€ FixtureTests/ +β”‚ β”‚ └── FixtureTests.swift +β”‚ β”œβ”€β”€ Fixtures/ +β”‚ β”‚ β”œβ”€β”€ CarthageProject/ +β”‚ β”‚ β”œβ”€β”€ SPM/ +β”‚ β”‚ β”œβ”€β”€ TestProject/ +β”‚ β”‚ β”œβ”€β”€ duplicated_include/ +β”‚ β”‚ β”œβ”€β”€ invalid_configs/ +β”‚ β”‚ β”œβ”€β”€ legacy_paths_test/ +β”‚ β”‚ β”œβ”€β”€ paths_test/ +β”‚ β”‚ β”œβ”€β”€ scheme_test/ +β”‚ β”‚ └── variables_test.yml +β”‚ β”œβ”€β”€ PerformanceTests/ +β”‚ β”‚ β”œβ”€β”€ PerformanceTests.swift +β”‚ β”‚ └── TestProject.swift +β”‚ β”œβ”€β”€ ProjectSpecTests/ +β”‚ β”œβ”€β”€ XcodeGenCoreTests/ +β”‚ β”œβ”€β”€ XcodeGenKitTests/ +β”‚ └── LinuxMain.swift +β”œβ”€β”€ scripts/ +β”‚ β”œβ”€β”€ archive.sh +β”‚ β”œβ”€β”€ build-fixtures.sh +β”‚ β”œβ”€β”€ diff-fixtures.sh +β”‚ β”œβ”€β”€ gen-fixtures.sh +β”‚ └── install.sh +β”œβ”€β”€ CHANGELOG.md +β”œβ”€β”€ CONTRIBUTING.md +β”œβ”€β”€ LICENSE +β”œβ”€β”€ Makefile +β”œβ”€β”€ Package.swift +β”œβ”€β”€ README.md +β”œβ”€β”€ RELEASE.md +└── _config.yml +``` + +--- + +## 3. Technical Implementation Details + +### Module Organization & Boundaries +- **`ProjectSpec` Module:** + Contains all domain models representing project configuration entities (targets, schemes, dependencies, build settings). Implements JSON/YAML serialization and validation logic. +- **`XcodeGenKit` Module:** + Implements the core project generation logic, converting `ProjectSpec` models into Xcode project files (`PBXProj`), schemes, and related artifacts. +- **`XcodeGenCore` Module:** + Provides utility functions and data structures (thread-safe wrappers, globbing, hashing, path manipulation) used across the project. +- **`XcodeGenCLI` Module:** + Implements the CLI interface, command parsing, error handling, and command execution orchestration. +- **`TestSupport` Module:** + Provides testing utilities and helpers to facilitate unit and integration tests. +- **`SettingPresets` Directory:** + Contains YAML presets for build configurations, platforms, products, and supported destinations, externalizing build environment details. + +### Key Interfaces & Implementations +- **Serialization Protocols:** + - `JSONObjectConvertible` and `JSONEncodable` protocols standardize JSON/YAML parsing and encoding across models. +- **Project Generation APIs:** + - `ProjectGenerator` and `PBXProjGenerator` classes provide methods to generate Xcode project files. +- **Build Settings Extraction:** + - `BuildSettingsExtractor` parses and validates build settings from configuration dictionaries. +- **CLI Commands:** + - `GenerateCommand`, `CacheCommand`, `DumpCommand` implement specific CLI functionalities. +- **Breakpoint & Scheme Generators:** + - Convert internal breakpoint and scheme models into Xcode-compatible formats. + +### Shared Data Structures & Types +- **Core Models:** `Project`, `Target`, `Scheme`, `Dependency`, `BuildScript`, `BuildRule`. +- **Enums:** `Platform`, `TargetType`, `ConfigType`, `Linkage`. +- **Utility Types:** `Path` (from `PathKit`), `Version`, `Atomic` wrapper for concurrency. + +### Communication Patterns +- **CLI to Core:** CLI commands parse arguments and invoke core generation or dumping functions. +- **Project Spec to Generator:** Models are parsed from YAML/JSON, validated, then passed to generators. +- **Generators to Filesystem:** Generated project files and plists are written atomically to disk. +- **Testing:** Test fixtures feed configurations into parsers and generators, asserting correctness. + +--- + +## 4. Development Patterns and Standards + +### Code Organization Principles +- **Modularization:** Clear separation between configuration models, generation logic, CLI, and utilities. +- **Protocol-Oriented Design:** Serialization and path resolution via protocols. +- **Single Responsibility:** Each struct/class models or handles a specific concern (e.g., `BuildScript`, `Breakpoint`). +- **Extensibility:** Use of templates, presets, and modular YAML includes supports scalable configuration. + +### Testing Strategies and Coverage +- **Unit Tests:** Cover parsing, validation, and generation logic (`ProjectSpecTests`, `XcodeGenCoreTests`, `XcodeGenKitTests`). +- **Integration Tests:** Use fixtures to test end-to-end project generation (`FixtureTests`). +- **Performance Tests:** Measure generation performance with large projects. +- **Test Fixtures:** Extensive YAML and resource fixtures simulate real-world project configurations. +- **BDD Style:** Use of `Spectre` framework for readable test descriptions. + +### Error Handling and Logging +- **Error Types:** Custom errors like `SpecValidationError`, `GenerationError` with descriptive messages. +- **Throwing Initializers:** Parsing and validation throw errors on invalid input. +- **CLI Error Reporting:** Errors are caught and displayed with colored messages. +- **Logging:** Minimal direct logging; relies on CLI output and test assertions. + +### Configuration Management Patterns +- **Externalized Configuration:** Build settings, platform presets, and product configurations are stored in YAML files. +- **Template Inheritance:** Targets and schemes support templates for reuse and override. +- **Variable Expansion:** Supports environment variable substitution in YAML. +- **Validation:** Configurations are validated before generation to prevent invalid projects. + +--- + +## 5. Integration and Dependencies + +### External Libraries +- **`XcodeProj`**: Core library for reading and writing Xcode project files. +- **`Yams`**: YAML parsing and serialization. +- **`JSONUtilities`**: JSON parsing and encoding helpers. +- **`PathKit`**: Filesystem path manipulation. +- **`Spectre`**: BDD testing framework. +- **`Rainbow`**: Colored CLI output. +- **`Version`**: Version parsing and comparison. +- **`SwiftCLI`**: CLI argument parsing and command management. + +### Internal Integrations +- **`ProjectSpec`** models are consumed by `XcodeGenKit` generators. +- **CLI commands** invoke generation and dumping logic in `XcodeGenKit`. +- **Test fixtures** in `Tests/Fixtures` are loaded and parsed by `ProjectSpec` and tested via `XcodeGenKit` and `XcodeGenCore`. +- **Scripts** in `scripts/` automate build, packaging, and fixture generation. + +### Build and Deployment Dependencies +- **Makefile** orchestrates build and release tasks. +- **Package.swift** defines Swift package targets and dependencies. +- **Scripts** automate packaging (`archive.sh`), fixture generation (`gen-fixtures.sh`), and installation (`install.sh`). + +--- + +## 6. Usage and Operational Guidance + +### Getting Started +- Use the CLI tool `xcodegen` (implemented in `Sources/XcodeGen/`) to generate Xcode projects from YAML/JSON specs. +- Define your project configuration in YAML files following the schema documented in `Docs/ProjectSpec.md`. +- Use `SettingPresets/` YAML files to customize build settings per platform or product. + +### Generating a Project +- Run `xcodegen generate` with your spec file path. +- The tool validates the spec, generates the `.xcodeproj` file, and writes Info.plist and entitlements as needed. +- Use `xcodegen dump` to output the resolved project spec for inspection. + +### Extending the Project +- Add new targets by defining them in the YAML spec under `targets`. +- Use `targetTemplates` and `schemeTemplates` to reuse configurations. +- Add new build settings or platform presets in `SettingPresets/`. +- Extend generators in `XcodeGenKit` for custom build phases or resource handling. + +### Testing +- Run unit and integration tests via `swift test`. +- Use fixtures under `Tests/Fixtures/` to simulate real-world project configurations. +- Use `scripts/gen-fixtures.sh` and `scripts/diff-fixtures.sh` to generate and validate test fixtures. + +### Debugging and Validation +- Validation errors are descriptive; consult `ProjectSpecTests` for common validation scenarios. +- Use `prettyFirstDifferenceBetweenStrings` utility in `XcodeGenCore/StringDiff.swift` for string diff debugging. +- Enable verbose CLI output for detailed logs. + +### Performance and Scalability +- The system supports large projects with multiple targets and schemes. +- Use caching (`CacheCommand`) to speed up repeated generation. +- Parallelized utilities in `XcodeGenCore` optimize performance. + +### Security and Compliance +- Code signing identities and entitlements are managed via build settings and presets. +- Use `strip-frameworks.sh` script (in `scripts/`) to remove invalid architectures and sign binaries correctly. + +### Monitoring and Observability +- No explicit monitoring; rely on CLI output and test coverage. +- Use test coverage reports and performance tests to ensure stability. + +--- + +# Summary + +This project is a comprehensive, modular, and extensible **Xcode project generation system** that leverages declarative YAML/JSON configuration, robust Swift data models, and a layered architecture to automate and validate complex multi-platform Apple project setups. It includes a CLI interface, extensive testing infrastructure, and build automation scripts, designed for scalability, maintainability, and integration into modern CI/CD pipelines. + +--- + +# End of DETAILS.md \ No newline at end of file