Skip to content

Commit cd23a75

Browse files
datlechindatlechin
committed
Add comprehensive DMG creation documentation
- Document DMG creation process and usage - Add troubleshooting guide for common issues - Explain Applications folder icon caching behavior - Include advanced usage and customization options - Document CI/CD integration - Add best practices for distribution
1 parent 0fc26f2 commit cd23a75

1 file changed

Lines changed: 185 additions & 0 deletions

File tree

‎DMG-README.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# DMG Installer Creation
2+
3+
This document explains how to create professional DMG installers for TablePro.
4+
5+
## Quick Start
6+
7+
```bash
8+
# Build the app first
9+
./build-release.sh arm64
10+
11+
# Create DMG
12+
./create-dmg.sh 0.1.13 arm64 build/Release/TablePro-arm64.app
13+
14+
# Test it
15+
open build/Release/TablePro-0.1.13-arm64.dmg
16+
```
17+
18+
## Features
19+
20+
✅ Professional drag-and-drop installation window
21+
✅ Applications folder symlink for easy installation
22+
✅ Custom background with visual arrow
23+
✅ Compressed format for smaller downloads
24+
✅ No Apple Developer account required
25+
26+
## Troubleshooting
27+
28+
### Applications Folder Icon Not Showing
29+
30+
If the Applications folder appears as just text without an icon:
31+
32+
**Why this happens:**
33+
- macOS caches folder icons and sometimes doesn't immediately recognize symlinks
34+
- This is a known macOS behavior, not a bug in the DMG
35+
36+
**Solutions:**
37+
38+
1. **Eject and re-mount** (Most reliable):
39+
```bash
40+
# Eject the DMG
41+
hdiutil detach "/Volumes/TablePro 0.1.13"
42+
43+
# Re-open it
44+
open build/Release/TablePro-0.1.13-arm64.dmg
45+
```
46+
The icon should appear correctly after re-mounting.
47+
48+
2. **Clear icon cache** (If problem persists):
49+
```bash
50+
sudo rm -rf /Library/Caches/com.apple.iconservices.store
51+
sudo find /private/var/folders/ -name com.apple.iconservices -exec rm -rf {} \;
52+
killall Finder
53+
```
54+
55+
3. **Force refresh**:
56+
- Open the DMG
57+
- Press `Cmd + Option + Esc`
58+
- Force quit Finder
59+
- Re-open the DMG
60+
61+
### Background Image Not Showing
62+
63+
If you see a plain gray background instead of the custom image:
64+
65+
**Requirements:**
66+
- ImageMagick must be installed: `brew install imagemagick`
67+
68+
**Check if installed:**
69+
```bash
70+
which magick # Should return: /opt/homebrew/bin/magick (or similar)
71+
```
72+
73+
**Without ImageMagick:**
74+
The DMG will still work perfectly fine, just without the custom background image.
75+
76+
## Advanced Usage
77+
78+
### Custom Background
79+
80+
Create your own background image:
81+
82+
```bash
83+
./create-dmg-background.sh [output-directory]
84+
```
85+
86+
This creates a 600x400 PNG image with:
87+
- Gradient background
88+
- Blue arrow pointing right
89+
- Installation instruction text
90+
91+
### Manual DMG Configuration
92+
93+
The script automatically:
94+
1. Creates a staging directory
95+
2. Copies the app bundle
96+
3. Creates Applications symlink
97+
4. Generates background image
98+
5. Sets Finder view options via AppleScript
99+
6. Compresses to final DMG
100+
101+
All settings can be modified in `create-dmg.sh`.
102+
103+
## CI/CD Integration
104+
105+
The GitHub Actions workflow automatically creates DMG files:
106+
107+
1. Builds app for both ARM64 and x86_64
108+
2. Creates DMG for each architecture
109+
3. Uploads as artifacts
110+
4. Includes in GitHub releases
111+
112+
See `.github/workflows/build.yml` for details.
113+
114+
## Best Practices
115+
116+
### For Distribution
117+
118+
1. **Always test the DMG** on a clean Mac before distributing
119+
2. **Eject and re-mount** to verify icons appear correctly
120+
3. **Test installation** by dragging to Applications
121+
4. **Check first launch** behavior (right-click → Open for unsigned apps)
122+
123+
### File Naming
124+
125+
The script uses this format:
126+
```
127+
TablePro-{version}-{architecture}.dmg
128+
```
129+
130+
Examples:
131+
- `TablePro-0.1.13-arm64.dmg` (Apple Silicon)
132+
- `TablePro-0.1.13-x86_64.dmg` (Intel)
133+
134+
### Size Optimization
135+
136+
DMG files are compressed with maximum compression:
137+
- Format: UDZO (compressed, read-only)
138+
- Compression: zlib level 9
139+
- Typical size: ~1-2 MB (depending on app size)
140+
141+
## Technical Details
142+
143+
### DMG Creation Process
144+
145+
1. **Staging**:
146+
- Creates temporary directory structure
147+
- Copies app and creates symlink
148+
- Generates background image
149+
150+
2. **Temporary DMG**:
151+
- Creates writable DMG with `hdiutil create`
152+
- Mounts with read-write permissions
153+
154+
3. **Configuration**:
155+
- Runs AppleScript to set Finder view options
156+
- Positions icons at specific coordinates
157+
- Sets background image
158+
159+
4. **Finalization**:
160+
- Ensures .DS_Store is written
161+
- Unmounts temporary DMG
162+
- Converts to compressed read-only format
163+
164+
### AppleScript Settings
165+
166+
The script configures:
167+
- Window size: 600x400 pixels
168+
- Icon view mode
169+
- Icon size: 72 pixels
170+
- No toolbar or status bar
171+
- Custom background image
172+
- Specific icon positions
173+
174+
## Compatibility
175+
176+
- **macOS Version**: 10.13+ (High Sierra and later)
177+
- **Architecture**: ARM64 (Apple Silicon) and x86_64 (Intel)
178+
- **Tools Required**:
179+
- `hdiutil` (built into macOS)
180+
- `osascript` (built into macOS)
181+
- `imagemagick` (optional, for custom backgrounds)
182+
183+
## License
184+
185+
These scripts are part of the TablePro project and follow the same license.

0 commit comments

Comments
 (0)