|
| 1 | +# Explr - macOS Distribution Guide |
| 2 | + |
| 3 | +## Building for Distribution |
| 4 | + |
| 5 | +### Quick Start - Universal Build (Recommended) |
| 6 | +```bash |
| 7 | +# Build for both Apple Silicon and Intel Macs |
| 8 | +./build-universal.sh |
| 9 | + |
| 10 | +# Or using npm |
| 11 | +npm run dist |
| 12 | +``` |
| 13 | + |
| 14 | +This creates distribution-ready DMG files for both architectures with all macOS frontend fixes applied. |
| 15 | + |
| 16 | +### Individual Architecture Builds |
| 17 | +```bash |
| 18 | +# Apple Silicon (M1/M2/M3/M4) only |
| 19 | +npm run tauri:build:macos |
| 20 | + |
| 21 | +# Intel Macs only |
| 22 | +npm run tauri:build:intel |
| 23 | +``` |
| 24 | + |
| 25 | +## Distribution Files |
| 26 | + |
| 27 | +After running the universal build, you'll find distribution files in: |
| 28 | +``` |
| 29 | +dist/file-explorer-0.2.3-macos/ |
| 30 | +├── Explr-0.2.3-aarch64.dmg # Apple Silicon (M-series) |
| 31 | +├── Explr-0.2.3-x86_64.dmg # Intel Macs |
| 32 | +├── checksums.sha256 # File verification |
| 33 | +└── README.md # User installation guide |
| 34 | +``` |
| 35 | + |
| 36 | +## Architecture Guide for Users |
| 37 | + |
| 38 | +### Apple Silicon Macs (Use aarch64 DMG) |
| 39 | +- **MacBook Air**: 2020 and later |
| 40 | +- **MacBook Pro**: 2020 and later (13", 14", 16") |
| 41 | +- **iMac**: 2021 and later (24") |
| 42 | +- **Mac Studio**: All models (2022+) |
| 43 | +- **Mac Pro**: 2023 and later |
| 44 | +- **Mac mini**: 2020 and later |
| 45 | + |
| 46 | +### Intel Macs (Use x86_64 DMG) |
| 47 | +- **MacBook Air**: 2019 and earlier |
| 48 | +- **MacBook Pro**: 2019 and earlier (13", 15", 16") |
| 49 | +- **iMac**: 2020 and earlier (21.5", 27") |
| 50 | +- **iMac Pro**: All models (2017-2021) |
| 51 | +- **Mac Pro**: 2013-2019 models |
| 52 | +- **Mac mini**: 2018 and earlier |
| 53 | + |
| 54 | +### How Users Can Check Their Mac Type |
| 55 | +```bash |
| 56 | +# Terminal command |
| 57 | +uname -m |
| 58 | +# arm64 = Apple Silicon → Use aarch64 DMG |
| 59 | +# x86_64 = Intel → Use x86_64 DMG |
| 60 | +``` |
| 61 | + |
| 62 | +Or: Apple Menu → About This Mac → Look for "Chip" (M1/M2/M3) or "Processor" (Intel) |
| 63 | + |
| 64 | +## File Sizes and Performance |
| 65 | + |
| 66 | +### Typical Build Sizes |
| 67 | +- **Apple Silicon DMG**: ~15-25 MB (optimized for M-series processors) |
| 68 | +- **Intel DMG**: ~18-30 MB (compatible with older Intel processors) |
| 69 | + |
| 70 | +### Performance Characteristics |
| 71 | +- **Apple Silicon**: Better performance, lower power consumption |
| 72 | +- **Intel**: Broader compatibility with older macOS versions |
| 73 | + |
| 74 | +## Distribution Checklist |
| 75 | + |
| 76 | +### Before Distribution |
| 77 | +- [ ] Run universal build: `./build-universal.sh` |
| 78 | +- [ ] Test Apple Silicon DMG on M-series Mac |
| 79 | +- [ ] Test Intel DMG on Intel Mac (if available) |
| 80 | +- [ ] Verify app launches and shows frontend on both |
| 81 | +- [ ] Check file integrity with checksums |
| 82 | +- [ ] Include README.md for users |
| 83 | + |
| 84 | +### Distribution Options |
| 85 | + |
| 86 | +#### 1. GitHub Releases |
| 87 | +```bash |
| 88 | +# Upload both DMG files to GitHub Releases |
| 89 | +# Include checksums.sha256 file |
| 90 | +# Add installation instructions in release notes |
| 91 | +``` |
| 92 | + |
| 93 | +#### 2. Direct Distribution |
| 94 | +- Host DMG files on your website |
| 95 | +- Provide clear download links for each architecture |
| 96 | +- Include the user guide (README.md) |
| 97 | + |
| 98 | +#### 3. Package Managers (Future) |
| 99 | +```bash |
| 100 | +# Homebrew cask (requires both architectures) |
| 101 | +brew install --cask file-explorer |
| 102 | +``` |
| 103 | + |
| 104 | +## Signing and Notarization (Optional) |
| 105 | + |
| 106 | +For wider distribution without security warnings: |
| 107 | + |
| 108 | +### 1. Code Signing (Requires Apple Developer Account) |
| 109 | +```bash |
| 110 | +# Sign the app bundle before creating DMG |
| 111 | +codesign --force --deep --sign "Developer ID Application: Your Name" path/to/app.app |
| 112 | +``` |
| 113 | + |
| 114 | +### 2. Notarization (Requires Apple Developer Account) |
| 115 | +```bash |
| 116 | +# Notarize the app with Apple |
| 117 | +xcrun notarytool submit file-explorer.dmg --keychain-profile "AC_PASSWORD" --wait |
| 118 | +``` |
| 119 | + |
| 120 | +### 3. Update Build Scripts |
| 121 | +Modify `src-tauri/scripts/post-build.sh` to use your signing certificate: |
| 122 | +```bash |
| 123 | +# Replace this line: |
| 124 | +codesign --force --deep --sign - "$APP_PATH" |
| 125 | + |
| 126 | +# With your certificate: |
| 127 | +codesign --force --deep --sign "Developer ID Application: Your Name" "$APP_PATH" |
| 128 | +``` |
| 129 | + |
| 130 | +## Troubleshooting Distribution |
| 131 | + |
| 132 | +### Common Issues |
| 133 | + |
| 134 | +1. **"App is damaged" error** |
| 135 | + - Users need to right-click → Open for first launch |
| 136 | + - Or use signed/notarized builds |
| 137 | + |
| 138 | +2. **Wrong architecture downloaded** |
| 139 | + - Provide clear download instructions |
| 140 | + - Consider creating an auto-detection webpage |
| 141 | + |
| 142 | +3. **App doesn't launch** |
| 143 | + - Ensure users downloaded the fixed DMG (with frontend fix) |
| 144 | + - Check macOS version compatibility (10.13+) |
| 145 | + |
| 146 | +### Build Issues |
| 147 | + |
| 148 | +1. **Rust target not found** |
| 149 | + ```bash |
| 150 | + rustup target add aarch64-apple-darwin |
| 151 | + rustup target add x86_64-apple-darwin |
| 152 | + ``` |
| 153 | + |
| 154 | +2. **Build fails on cross-compilation** |
| 155 | + - Ensure Xcode Command Line Tools are installed |
| 156 | + - Some dependencies might not support cross-compilation |
| 157 | + |
| 158 | +3. **DMG creation fails** |
| 159 | + - Check disk space |
| 160 | + - Ensure no existing mounts with same name |
| 161 | + |
| 162 | +## Version Management |
| 163 | + |
| 164 | +### Updating Versions |
| 165 | +1. Update version in `package.json` |
| 166 | +2. Update version in `src-tauri/Cargo.toml` |
| 167 | +3. Update version in `src-tauri/tauri.conf.json` |
| 168 | +4. Run universal build to generate new DMGs |
| 169 | + |
| 170 | +### Release Naming Convention |
| 171 | +- `file-explorer-[VERSION]-aarch64.dmg` - Apple Silicon |
| 172 | +- `file-explorer-[VERSION]-x86_64.dmg` - Intel |
| 173 | +- Example: `Explr-0.2.3-aarch64.dmg` |
| 174 | + |
| 175 | +## Automated Distribution (CI/CD) |
| 176 | + |
| 177 | +### GitHub Actions Example |
| 178 | +```yaml |
| 179 | +name: Build and Release |
| 180 | +on: |
| 181 | + release: |
| 182 | + types: [published] |
| 183 | + |
| 184 | +jobs: |
| 185 | + build-macos: |
| 186 | + runs-on: macos-latest |
| 187 | + steps: |
| 188 | + - uses: actions/checkout@v3 |
| 189 | + - name: Setup Node |
| 190 | + uses: actions/setup-node@v3 |
| 191 | + with: |
| 192 | + node-version: '18' |
| 193 | + - name: Setup Rust |
| 194 | + uses: dtolnay/rust-toolchain@stable |
| 195 | + with: |
| 196 | + targets: aarch64-apple-darwin,x86_64-apple-darwin |
| 197 | + - name: Install dependencies fast |
| 198 | + run: npm ci --no-audit --no-fund --ignore-scripts |
| 199 | + - name: Build universal |
| 200 | + env: |
| 201 | + CI: "true" # skip Finder AppleScript during DMG creation |
| 202 | + run: npm run dist |
| 203 | + - name: Upload assets |
| 204 | + uses: actions/upload-release-asset@v1 |
| 205 | + with: |
| 206 | + upload_url: ${{ github.event.release.upload_url }} |
| 207 | + asset_path: ./dist/file-explorer-0.2.3-macos/ |
| 208 | +``` |
| 209 | +
|
| 210 | +## Support and Maintenance |
| 211 | +
|
| 212 | +### User Support |
| 213 | +- Provide clear architecture detection instructions |
| 214 | +- Include troubleshooting steps in distribution |
| 215 | +- Consider creating a support webpage |
| 216 | +
|
| 217 | +### Maintenance |
| 218 | +- Test new macOS versions when released |
| 219 | +- Update Rust/Tauri dependencies regularly |
| 220 | +- Monitor for architecture-specific issues |
| 221 | +
|
| 222 | +--- |
| 223 | +
|
| 224 | +## Quick Reference |
| 225 | +
|
| 226 | +### Build Commands |
| 227 | +```bash |
| 228 | +./build-universal.sh # Build for both architectures (recommended) |
| 229 | +npm run dist # Same as above |
| 230 | +npm run tauri:build:macos # Apple Silicon only |
| 231 | +npm run tauri:build:intel # Intel only |
| 232 | +``` |
| 233 | + |
| 234 | +### File Locations |
| 235 | +```bash |
| 236 | +dist/Explr-0.2.3-macos/ # Distribution files |
| 237 | +target/*/release/bundle/dmg/ # Individual build outputs |
| 238 | +checksums.sha256 # Verification hashes |
| 239 | +``` |
| 240 | + |
| 241 | +### Architecture Detection |
| 242 | +```bash |
| 243 | +uname -m # Terminal command |
| 244 | +system_profiler SPHardwareDataType | grep Chip # Detailed info |
| 245 | +``` |
0 commit comments