Skip to content

Commit 7745ca6

Browse files
Copilotefremidze
Copilot
and
efremidze
committed
Create comprehensive .github/copilot-instructions.md with validated commands
Co-authored-by: efremidze <2286277+efremidze@users.noreply.github.com>
1 parent cd30fe3 commit 7745ca6

1 file changed

Lines changed: 154 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# VisualEffectView iOS Library
2+
3+
VisualEffectView is a dynamic blur background view with tint color (UIVisualEffectView subclass) for iOS 14.0+ written in Swift 5.9+. It supports SwiftUI and has distribution via Swift Package Manager, CocoaPods, and Carthage.
4+
5+
**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
6+
7+
## CRITICAL: Platform Requirements
8+
9+
**This codebase ONLY builds and runs on macOS with Xcode installed. It cannot be built on Linux environments.**
10+
11+
- **REQUIRED**: macOS with Xcode compatible with Swift 5.9+
12+
- **REQUIRED**: iOS 14.0+ for deployment target
13+
- Build tools: `xcodebuild`, Swift Package Manager, CocoaPods, Carthage
14+
- Validation tools: SwiftLint
15+
16+
## Working Effectively
17+
18+
### Bootstrap and Environment Setup
19+
- **REQUIRED**: Install Xcode from Mac App Store or developer.apple.com
20+
- **REQUIRED**: Install command line tools: `xcode-select --install`
21+
- Install SwiftLint: `brew install swiftlint`
22+
- Install CocoaPods: `sudo gem install cocoapods`
23+
- Install Carthage: `brew install carthage`
24+
25+
### Building the Library
26+
**NEVER CANCEL: All build commands require patience. Use 60+ minute timeouts.**
27+
28+
#### Swift Package Manager
29+
- Basic build: `swift build --triple arm64-apple-ios14.0 --sdk $(xcrun --sdk iphoneos --show-sdk-path)`
30+
- Build time: ~30-60 seconds on modern Mac. NEVER CANCEL - set timeout to 300+ seconds.
31+
32+
#### Xcode Project
33+
- Build library: `xcodebuild -project "VisualEffectView.xcodeproj" -scheme "VisualEffectView" -sdk iphoneos CODE_SIGNING_ALLOWED=NO clean build`
34+
- Build Example app: `xcodebuild -project "VisualEffectView.xcodeproj" -scheme "Example" -sdk iphonesimulator CODE_SIGNING_ALLOWED=NO clean build`
35+
- Build time: ~2-5 minutes depending on clean state. NEVER CANCEL - set timeout to 600+ seconds.
36+
37+
#### Alternative: Open in Xcode
38+
- Open `VisualEffectView.xcodeproj` in Xcode
39+
- Select "Example" scheme and iOS Simulator
40+
- Press Cmd+B to build or Cmd+R to run
41+
42+
### Validation and Testing
43+
44+
#### SwiftLint (Required before commits)
45+
- Run linting: `swiftlint lint`
46+
- **Timing**: 15-30 seconds. NEVER CANCEL - set timeout to 60+ seconds.
47+
- **CRITICAL**: Code must pass SwiftLint validation or CI will fail.
48+
49+
#### CocoaPods Validation
50+
- Validate podspec: `pod lib lint VisualEffectView.podspec --allow-warnings`
51+
- **Timing**: 30-120 seconds depending on network. NEVER CANCEL - set timeout to 300+ seconds.
52+
- **Note**: Requires `--allow-warnings` flag due to documentation URL warning.
53+
54+
#### Manual Functionality Testing (REQUIRED)
55+
**ALWAYS test these scenarios after making changes:**
56+
57+
1. **Build and Run Example App**:
58+
- Open Example app in iOS Simulator
59+
- Verify the blur effect grid displays correctly
60+
- Test the blur radius slider - effects should change in real-time
61+
- Take a screenshot to verify visual output
62+
- **Timing**: 2-3 minutes to build and launch. NEVER CANCEL - set timeout to 600+ seconds.
63+
64+
2. **SwiftUI Integration Test**:
65+
- Verify VisualEffect SwiftUI view renders properly
66+
- Test with different colorTint values (red, blue, green, etc.)
67+
- Test colorTintAlpha values from 0.0 to 1.0
68+
- Test blurRadius values from 0 to 20
69+
70+
3. **UIKit Integration Test**:
71+
- Create a simple UIKit app that uses VisualEffectView directly
72+
- Test programmatic creation and property changes
73+
- Verify dynamic property updates work correctly
74+
75+
### Common Commands Reference
76+
77+
#### Repository Structure
78+
```
79+
VisualEffectView/
80+
├── .github/ # CI workflows and templates
81+
│ ├── workflows/
82+
│ │ ├── ci.yml # Xcode build validation
83+
│ │ ├── lint.yml # SwiftLint validation
84+
│ │ └── swift.yml # Swift Package Manager build
85+
├── Example/ # SwiftUI example app
86+
│ ├── ContentView.swift # Main demo interface
87+
│ └── ExampleApp.swift # App entry point
88+
├── Sources/ # Library source code
89+
│ ├── VisualEffectView.swift # Main UIKit implementation
90+
│ ├── VisualEffectView+SwiftUI.swift # SwiftUI wrapper
91+
│ └── UIViewEffectView+Helpers.swift # Private API helpers
92+
├── Package.swift # Swift Package Manager config
93+
├── VisualEffectView.podspec # CocoaPods config
94+
├── .swiftlint.yml # SwiftLint configuration
95+
└── VisualEffectView.xcodeproj # Xcode project
96+
```
97+
98+
#### Quick Development Workflow
99+
1. `git checkout -b feature/your-feature-name`
100+
2. Make changes to source files in `Sources/`
101+
3. `swiftlint lint` - verify no style violations
102+
4. `xcodebuild -project "VisualEffectView.xcodeproj" -scheme "Example" -sdk iphonesimulator CODE_SIGNING_ALLOWED=NO clean build` - verify Example builds
103+
5. Launch Example in iOS Simulator and test functionality
104+
6. `pod lib lint VisualEffectView.podspec --allow-warnings` - verify CocoaPods compatibility
105+
7. Commit and push changes
106+
107+
#### CI Pipeline Commands (for reference)
108+
- SwiftLint: `swiftlint lint` (~15 seconds)
109+
- Xcode build: `xcodebuild -project "VisualEffectView.xcodeproj" -scheme "Example" CODE_SIGNING_ALLOWED=NO clean build` (~2-5 minutes)
110+
- Swift Package: `swift build --triple arm64-apple-ios14.0 --sdk $(xcrun --sdk iphoneos --show-sdk-path)` (~30-60 seconds)
111+
112+
## Distribution and Release
113+
114+
### Swift Package Manager
115+
- Package configuration: `Package.swift`
116+
- Platform: iOS 14.0+
117+
- Swift version: 5.9+
118+
119+
### CocoaPods
120+
- Podspec: `VisualEffectView.podspec`
121+
- Version: 5.0.0
122+
- Installation: `pod "VisualEffectView"`
123+
124+
### Carthage
125+
- Installation: `github "efremidze/VisualEffectView"`
126+
- Framework: `VisualEffectView.framework`
127+
128+
## Troubleshooting
129+
130+
### Build Failures
131+
- **UIKit not found**: You're on Linux - this library requires macOS with Xcode
132+
- **xcodebuild not found**: Install Xcode and command line tools
133+
- **Signing errors**: Add `CODE_SIGNING_ALLOWED=NO` to xcodebuild commands
134+
- **Simulator not found**: Launch Xcode and install iOS Simulator components
135+
136+
### SwiftLint Failures
137+
- **swiftlint not found**: Install with `brew install swiftlint`
138+
- **Style violations**: Fix issues or update `.swiftlint.yml` if justified
139+
- **Disabled rules**: Current config disables force_cast, identifier_name, line_length, trailing_whitespace
140+
141+
### Runtime Issues
142+
- **Blur effect not working**: This library uses private UIKit APIs - test on device/simulator, not just build validation
143+
- **SwiftUI preview crashes**: Ensure iOS 14.0+ deployment target in hosting app
144+
- **Performance issues**: Blur effects are GPU-intensive - test on real devices
145+
146+
## Important Notes
147+
148+
- **Private API Usage**: This library uses private UIKit APIs (`_UICustomBlurEffect`, `_UIVisualEffectBackdropView`) for enhanced blur effects
149+
- **App Store Risk**: Apple may reject apps using private APIs - use with caution in production
150+
- **iOS Version Support**: Only supports iOS 14.0+ due to API dependencies
151+
- **No Unit Tests**: Validation relies on manual testing with Example app and visual verification
152+
- **Documentation**: API documentation generated with Jazzy, available at https://efremidze.github.io/VisualEffectView/
153+
154+
**Remember**: Always validate changes by running the Example app and testing visual effects functionality. Screenshots of the working app are the best validation that changes work correctly.

0 commit comments

Comments
 (0)