HereIAm/DISTRIBUTION.md

HereIAm Distribution Guide

Building for macOS Distribution

Quick Start

# 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

# 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

# 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

# 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:

# 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:

# 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):

# 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:

# 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

# Homebrew Cask (example)
brew install --cask hereiam

Testing the Build

Local Testing:

# 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:

# 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:

# 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:

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:

__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