243 lines
7.1 KiB
Markdown
243 lines
7.1 KiB
Markdown
# 4DSTAR Bundle Manager .pkg Installer Guide
|
|
|
|
## Overview
|
|
|
|
The 4DSTAR Bundle Manager now includes a professional macOS `.pkg` installer that provides a seamless installation experience with automatic file association setup and dependency guidance.
|
|
|
|
## What's Included
|
|
|
|
### 📦 **Professional Installer Package**
|
|
- Native macOS `.pkg` installer format
|
|
- Automatic Launch Services refresh
|
|
- File association setup
|
|
- Custom icon registration
|
|
- Dependency information dialogs
|
|
|
|
### 🔧 **Automatic Post-Install Setup**
|
|
- Launch Services database refresh
|
|
- File association registration
|
|
- Icon cache clearing
|
|
- Finder restart for immediate functionality
|
|
|
|
### 📋 **User Guidance**
|
|
- Welcome dialog explaining system requirements
|
|
- Clear distinction between basic and advanced usage
|
|
- Optional dependency installation instructions
|
|
- Conclusion dialog with next steps
|
|
|
|
## Installation Experience
|
|
|
|
### 1. **Welcome Screen**
|
|
Users see a comprehensive welcome dialog that explains:
|
|
- **Basic Usage**: No dependencies required for bundle management
|
|
- **Advanced Usage**: Docker and Meson needed for plugin building
|
|
- **System Requirements**: macOS 10.12+ minimum
|
|
- **What's Included**: App, file associations, custom icons
|
|
|
|
### 2. **Standard macOS Installation**
|
|
- License agreement (if configured)
|
|
- Installation destination (defaults to /Applications)
|
|
- Administrator password prompt
|
|
- Installation progress
|
|
|
|
### 3. **Automatic Post-Install**
|
|
The installer automatically:
|
|
- Refreshes Launch Services database
|
|
- Registers file associations for .fbundle and .opat files
|
|
- Clears icon caches
|
|
- Restarts Finder
|
|
- Logs all operations to `/tmp/4dstar-postinstall.log`
|
|
|
|
### 4. **Conclusion Screen**
|
|
Users see a success dialog with:
|
|
- Installation confirmation
|
|
- Getting started instructions
|
|
- Optional dependency installation commands
|
|
- Troubleshooting information
|
|
|
|
## File Associations
|
|
|
|
### Supported File Types
|
|
- **`.fbundle`**: 4DSTAR Plugin Bundle Files
|
|
- **`.opat`**: OPAT Data Files
|
|
|
|
### What Works After Installation
|
|
- ✅ Double-click files to open in 4DSTAR Bundle Manager
|
|
- ✅ Right-click → "Open with 4DSTAR Bundle Manager"
|
|
- ✅ Custom file icons in Finder
|
|
- ✅ Proper file type descriptions
|
|
- ✅ Immediate functionality (no restart required)
|
|
|
|
## Dependencies
|
|
|
|
### Required (Always)
|
|
- macOS 10.12 or later
|
|
- No additional dependencies for basic bundle management
|
|
|
|
### Optional (Advanced Features)
|
|
- **Docker Desktop**: For cross-platform plugin builds
|
|
- **Meson Build System**: For native plugin compilation
|
|
- **Xcode Command Line Tools**: For C++ compilation
|
|
|
|
### Installation Commands (Optional)
|
|
```bash
|
|
# Install Xcode Command Line Tools
|
|
xcode-select --install
|
|
|
|
# Install Meson via Homebrew
|
|
brew install meson
|
|
|
|
# Download Docker Desktop
|
|
# Visit: https://docker.com/products/docker-desktop
|
|
```
|
|
|
|
## Build Configuration
|
|
|
|
### Package.json Configuration
|
|
```json
|
|
{
|
|
"build": {
|
|
"mac": {
|
|
"target": [
|
|
{ "target": "dmg", "arch": ["x64", "arm64"] },
|
|
{ "target": "pkg", "arch": ["x64", "arm64"] },
|
|
{ "target": "zip", "arch": ["x64", "arm64"] }
|
|
]
|
|
},
|
|
"pkg": {
|
|
"scripts": "installer-scripts",
|
|
"welcome": "installer-resources/welcome.html",
|
|
"conclusion": "installer-resources/conclusion.html",
|
|
"installLocation": "/Applications",
|
|
"mustClose": ["com.fourdst.bundlemanager"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### File Structure
|
|
```
|
|
electron/
|
|
├── installer-scripts/
|
|
│ └── postinstall # Post-install script
|
|
├── installer-resources/
|
|
│ ├── welcome.html # Welcome dialog
|
|
│ └── conclusion.html # Conclusion dialog
|
|
├── icons/
|
|
│ ├── app-icon.icns # Main app icon
|
|
│ ├── fbundle-icon.icns # .fbundle file icon
|
|
│ └── opat-icon.icns # .opat file icon
|
|
└── package.json # Build configuration
|
|
```
|
|
|
|
## Building the Installer
|
|
|
|
### Generate All Installers
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
### Generate Only .pkg
|
|
```bash
|
|
npx electron-builder --mac pkg
|
|
```
|
|
|
|
### Output Files
|
|
- `dist/4DSTAR Bundle Manager-1.0.0.pkg` (x64)
|
|
- `dist/4DSTAR Bundle Manager-1.0.0-arm64.pkg` (ARM64)
|
|
- Plus traditional .dmg and .zip files
|
|
|
|
## Post-Install Script Details
|
|
|
|
### What It Does
|
|
```bash
|
|
#!/bin/bash
|
|
# Reset Launch Services database
|
|
lsregister -kill -r -domain local -domain system -domain user
|
|
|
|
# Register the app bundle
|
|
lsregister -f "/Applications/4DSTAR Bundle Manager.app"
|
|
|
|
# Clear icon caches
|
|
rm -rf ~/Library/Caches/com.apple.iconservices.store
|
|
rm -rf /Library/Caches/com.apple.iconservices.store
|
|
|
|
# Restart Finder
|
|
killall Finder
|
|
```
|
|
|
|
### Logging
|
|
All operations are logged to `/tmp/4dstar-postinstall.log` for troubleshooting.
|
|
|
|
## Troubleshooting
|
|
|
|
### If File Associations Don't Work
|
|
1. Check post-install log: `cat /tmp/4dstar-postinstall.log`
|
|
2. Manually refresh: `npm run refresh-icons`
|
|
3. Right-click file → Get Info → Change default app
|
|
|
|
### If Icons Don't Appear
|
|
1. Wait 2-3 minutes for macOS to update
|
|
2. Log out and back in
|
|
3. Restart the Mac
|
|
4. Check icon cache clearing in post-install log
|
|
|
|
### If Installation Fails
|
|
1. Ensure you have administrator privileges
|
|
2. Close any running instances of the app
|
|
3. Check available disk space (>200MB required)
|
|
4. Try installing from a different location
|
|
|
|
## Developer Notes
|
|
|
|
### Testing the Installer
|
|
1. Build the .pkg installer
|
|
2. Test on a clean macOS system or VM
|
|
3. Verify file associations work immediately
|
|
4. Check that icons appear in Finder
|
|
5. Test with both .fbundle and .opat files
|
|
|
|
### Customizing Dialogs
|
|
- Edit `installer-resources/welcome.html` for welcome content
|
|
- Edit `installer-resources/conclusion.html` for conclusion content
|
|
- HTML/CSS styling is supported
|
|
- Keep content concise and user-friendly
|
|
|
|
### Modifying Post-Install Script
|
|
- Edit `installer-scripts/postinstall`
|
|
- Ensure script remains executable: `chmod +x postinstall`
|
|
- Test thoroughly on different macOS versions
|
|
- Add logging for all operations
|
|
|
|
## Distribution
|
|
|
|
### Recommended Distribution Method
|
|
1. **Primary**: `.pkg` installer for best user experience
|
|
2. **Alternative**: `.dmg` for users who prefer disk images
|
|
3. **Developer**: `.zip` for automated deployment
|
|
|
|
### Code Signing (Production)
|
|
For production distribution:
|
|
1. Obtain Apple Developer ID certificate
|
|
2. Configure code signing in package.json
|
|
3. Notarize the installer with Apple
|
|
4. Test on systems with Gatekeeper enabled
|
|
|
|
## User Support
|
|
|
|
### Common User Questions
|
|
|
|
**Q: Do I need Docker to use the app?**
|
|
A: No, Docker is only needed for building plugins. Basic bundle management works without any additional software.
|
|
|
|
**Q: Why do I need administrator privileges?**
|
|
A: The installer needs to install the app to /Applications and register file associations system-wide.
|
|
|
|
**Q: Can I install to a different location?**
|
|
A: The .pkg installer installs to /Applications by default. Use the .dmg version for custom locations.
|
|
|
|
**Q: Will this work on older Macs?**
|
|
A: Yes, the app supports macOS 10.12 and later on both Intel and Apple Silicon Macs.
|
|
|
|
This comprehensive installer solution provides a professional, user-friendly installation experience that handles all technical setup automatically while clearly communicating optional dependencies to users.
|