Initial commit: HereIAm mouse movement monitor
- Complete macOS application with PyQt5 GUI - Smart mouse monitoring with configurable timing - System menu bar integration with adaptive theming - Comprehensive build system with PyInstaller - Professional DMG creation for distribution - Full documentation and testing scripts
This commit is contained in:
Jerico Thomas
245
DISTRIBUTION.md
Normal file
245
DISTRIBUTION.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# HereIAm Distribution Guide
|
||||
|
||||
## Building for macOS Distribution
|
||||
|
||||
### Quick Start
|
||||
```bash
|
||||
# 1. Build the .app
|
||||
./build_app.sh
|
||||
|
||||
# 2. Create distributable DMG
|
||||
./create_dmg.sh
|
||||
|
||||
# 3. Your app is ready at: dist/HereIAm-1.0.0.dmg
|
||||
```
|
||||
|
||||
### Detailed Build Process
|
||||
|
||||
#### Prerequisites
|
||||
- macOS 10.14+ (for building)
|
||||
- Python 3.8+
|
||||
- Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
#### Step 1: Environment Setup
|
||||
```bash
|
||||
# Clone and setup
|
||||
git clone <your-repo>
|
||||
cd HereIAm
|
||||
|
||||
# Create virtual environment
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
pip install -r requirements-build.txt
|
||||
```
|
||||
|
||||
#### Step 2: Build the Application
|
||||
```bash
|
||||
# Build .app bundle
|
||||
./build_app.sh
|
||||
```
|
||||
|
||||
This creates `dist/HereIAm.app` with:
|
||||
- All dependencies bundled
|
||||
- Icons and assets included
|
||||
- Menu bar-only app (no dock icon)
|
||||
- Ready to run on any macOS 10.14+ system
|
||||
|
||||
#### Step 3: Create Distribution Package
|
||||
```bash
|
||||
# Create DMG for distribution
|
||||
./create_dmg.sh
|
||||
```
|
||||
|
||||
This creates `dist/HereIAm-1.0.0.dmg` with:
|
||||
- Drag-to-Applications installer
|
||||
- Professional DMG layout
|
||||
- README instructions
|
||||
- Compressed for smaller download
|
||||
|
||||
### Code Signing (Recommended for Distribution)
|
||||
|
||||
#### For Developer ID Distribution:
|
||||
```bash
|
||||
# Sign the app
|
||||
codesign --deep --force --verify --verbose \
|
||||
--sign "Developer ID Application: Your Name (TEAM_ID)" \
|
||||
dist/HereIAm.app
|
||||
|
||||
# Verify signing
|
||||
codesign --verify --verbose dist/HereIAm.app
|
||||
spctl --assess --verbose dist/HereIAm.app
|
||||
```
|
||||
|
||||
#### For Mac App Store:
|
||||
```bash
|
||||
# Sign for App Store
|
||||
codesign --deep --force --verify --verbose \
|
||||
--sign "3rd Party Mac Developer Application: Your Name (TEAM_ID)" \
|
||||
dist/HereIAm.app
|
||||
|
||||
# Create installer package
|
||||
productbuild --component dist/HereIAm.app /Applications \
|
||||
--sign "3rd Party Mac Developer Installer: Your Name (TEAM_ID)" \
|
||||
HereIAm.pkg
|
||||
```
|
||||
|
||||
### Notarization (Required for Gatekeeper)
|
||||
|
||||
#### Setup (one-time):
|
||||
```bash
|
||||
# Store credentials
|
||||
xcrun notarytool store-credentials "AC_PASSWORD" \
|
||||
--apple-id "your-email@example.com" \
|
||||
--team-id "YOUR_TEAM_ID" \
|
||||
--password "app-specific-password"
|
||||
```
|
||||
|
||||
#### Notarize DMG:
|
||||
```bash
|
||||
# Submit for notarization
|
||||
xcrun notarytool submit dist/HereIAm-1.0.0.dmg \
|
||||
--keychain-profile "AC_PASSWORD" --wait
|
||||
|
||||
# Staple the notarization
|
||||
xcrun stapler staple dist/HereIAm-1.0.0.dmg
|
||||
```
|
||||
|
||||
### Distribution Options
|
||||
|
||||
#### 1. Direct Download
|
||||
- Upload DMG to your website
|
||||
- Users download and install manually
|
||||
- Requires code signing for smooth installation
|
||||
|
||||
#### 2. Mac App Store
|
||||
- Most secure distribution
|
||||
- Apple handles updates
|
||||
- Requires App Store review process
|
||||
- Need to modify app for sandboxing requirements
|
||||
|
||||
#### 3. Package Managers
|
||||
```bash
|
||||
# Homebrew Cask (example)
|
||||
brew install --cask hereiam
|
||||
```
|
||||
|
||||
### Testing the Build
|
||||
|
||||
#### Local Testing:
|
||||
```bash
|
||||
# Test the app bundle
|
||||
open dist/HereIAm.app
|
||||
|
||||
# Test the DMG
|
||||
open dist/HereIAm-1.0.0.dmg
|
||||
```
|
||||
|
||||
#### Distribution Testing:
|
||||
1. Test on clean macOS system
|
||||
2. Verify all dependencies are bundled
|
||||
3. Check accessibility permissions prompt
|
||||
4. Test menu bar functionality
|
||||
5. Verify icon changes with system theme
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
#### Common Build Issues:
|
||||
|
||||
**PyInstaller import errors:**
|
||||
```bash
|
||||
# Add missing imports to HereIAm.spec hiddenimports
|
||||
hiddenimports=[
|
||||
'PyQt5.QtCore',
|
||||
'PyQt5.QtGui',
|
||||
'PyQt5.QtWidgets',
|
||||
'pyautogui',
|
||||
'missing_module_name',
|
||||
]
|
||||
```
|
||||
|
||||
**Missing assets:**
|
||||
- Verify all `.icns` files are in `assets/`
|
||||
- Check file permissions
|
||||
- Ensure assets are copied in spec file
|
||||
|
||||
**Large bundle size:**
|
||||
- Review excludes in spec file
|
||||
- Remove unused dependencies
|
||||
- Use UPX compression (enabled by default)
|
||||
|
||||
**Gatekeeper issues:**
|
||||
- Code sign the application
|
||||
- Notarize with Apple
|
||||
- Test with: `spctl --assess --verbose dist/HereIAm.app`
|
||||
|
||||
#### Performance Optimization:
|
||||
|
||||
**Reduce bundle size:**
|
||||
```python
|
||||
# In HereIAm.spec, add to excludes:
|
||||
excludes=[
|
||||
'tkinter', 'unittest', 'email', 'http', 'urllib', 'xml',
|
||||
'pydoc', 'doctest', 'argparse', 'difflib', 'inspect',
|
||||
'calendar', 'pprint', 'pdb', 'bdb', 'cmd', 'pstats',
|
||||
]
|
||||
```
|
||||
|
||||
**Faster startup:**
|
||||
- Minimize imports in main.py
|
||||
- Use lazy imports where possible
|
||||
- Optimize icon loading
|
||||
|
||||
### Continuous Integration
|
||||
|
||||
#### GitHub Actions Example:
|
||||
```yaml
|
||||
name: Build macOS App
|
||||
|
||||
on: [push, release]
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: macos-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Setup Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.11'
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip install -r requirements.txt
|
||||
pip install -r requirements-build.txt
|
||||
- name: Build app
|
||||
run: ./build_app.sh
|
||||
- name: Create DMG
|
||||
run: ./create_dmg.sh
|
||||
- name: Upload artifacts
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: HereIAm-macOS
|
||||
path: dist/HereIAm-*.dmg
|
||||
```
|
||||
|
||||
### Version Management
|
||||
|
||||
Update version in `src/__init__.py`:
|
||||
```python
|
||||
__version__ = "1.1.0" # Update this for new releases
|
||||
```
|
||||
|
||||
### Support and Maintenance
|
||||
|
||||
#### User Support:
|
||||
- Provide clear installation instructions
|
||||
- Document accessibility permission requirements
|
||||
- Include troubleshooting in README
|
||||
- Offer support email (jerico@tekop.net)
|
||||
|
||||
#### Updates:
|
||||
- Use semantic versioning (1.0.0 → 1.0.1 → 1.1.0)
|
||||
- Test on multiple macOS versions
|
||||
- Consider auto-update mechanism for future versions
|
||||
Reference in New Issue
Block a user