# AppIcon Setup Instructions

To ensure your AppIcon is properly included in the build, follow these steps:

## 1. Verify Asset Catalog Exists

1. In Xcode's Project Navigator (left sidebar), look for a file named `Assets.xcassets`
2. If it doesn't exist, create it:
   - Right-click on your project folder
   - Select **New File...**
   - Choose **Asset Catalog** under Resource
   - Name it `Assets.xcassets`

## 2. Add AppIcon to Asset Catalog

1. Open `Assets.xcassets` in Xcode
2. In the left sidebar of the asset catalog, you should see "AppIcon"
3. If "AppIcon" doesn't exist:
   - Click the **+** button at the bottom of the asset list
   - Select **App Icons & Launch Images > macOS App Icon**
   - Name it "AppIcon"

## 3. Add Your Icon Images

You need to provide icon images at various sizes. For macOS apps, you typically need:

- **16x16** (1x and 2x) - For Finder and menu bar
- **32x32** (1x and 2x) - For Finder
- **128x128** (1x and 2x) - For Finder and Dock
- **256x256** (1x and 2x) - For Finder and Dock
- **512x512** (1x and 2x) - For Finder and Dock

Drag and drop your icon files into the appropriate slots in the AppIcon asset.

**Tip:** You can create all sizes from a single 1024×1024 PNG using:
- Preview (export at different sizes)
- Third-party tools like [Icon Set Creator](https://apps.apple.com/app/icon-set-creator/id939343785)
- Command line with `sips` tool

## 4. Configure Target Settings

1. Select your project in the Project Navigator
2. Select your app target
3. Go to the **General** tab
4. Under **App Icons and Launch Screen**:
   - **App Icon**: Should be set to "AppIcon" (from Assets.xcassets)
   - If it shows "AppIcon - AppIcon", that's correct
5. Under **Build Settings** tab:
   - Search for "Asset Catalog Compiler"
   - Ensure **Asset Catalog Compiler - Options > App Icon Set Name** is set to "AppIcon"

## 5. Verify Info.plist

Your Info.plist should NOT have a `CFBundleIconFile` key if you're using an asset catalog. The asset catalog automatically handles icon registration.

If you see this key in Info.plist, you can safely remove it when using Assets.xcassets.

## 6. Clean and Rebuild

After setting up the icon:

1. In Xcode menu: **Product > Clean Build Folder** (⇧⌘K)
2. **Product > Build** (⌘B)
3. **Product > Run** (⌘R)

Your icon should now appear in:
- The Dock when the app is running
- Finder when viewing the built .app bundle
- The Applications folder
- Spotlight search results

## Troubleshooting

If the icon still doesn't appear:

1. **Check file format**: Icons must be PNG files
2. **Check transparency**: AppKit will render transparent areas
3. **Restart Xcode**: Sometimes Xcode's cache needs to be cleared
4. **Delete derived data**:
   - Xcode menu > Preferences > Locations
   - Click the arrow next to Derived Data path
   - Delete the folder for your project
   - Rebuild
5. **Reset icon cache** (macOS):
   ```bash
   sudo rm -rf /Library/Caches/com.apple.iconservices.store
   killall Dock
   killall Finder
   ```

## Quick Single-File Icon (Alternative)

If you prefer not to use an asset catalog, you can use a single .icns file:

1. Create a .icns file containing all icon sizes (use Icon Composer or third-party tools)
2. Add the .icns file to your project
3. In Info.plist, add:
   - Key: `CFBundleIconFile`
   - Value: Your icon filename **without** the .icns extension
4. Ensure the .icns file is included in the target's **Copy Bundle Resources** build phase

The asset catalog method is recommended for modern Xcode projects.
