path-juggler/DEBUGGING.md

Debugging Path Juggler

Build System

The build scripts use uv to manage Python versions and dependencies, ensuring a truly self-contained build that doesn't depend on system Python installations. This means:

• ✅ No dependency on system Python versions
• ✅ No dependency on Homebrew Python
• ✅ Consistent builds across different systems
• ✅ Self-contained .app bundle with everything included

The Problem

When you launch the built app and nothing happens, it's because:

1. The app is built with console=False, so errors are hidden
2. The app is failing silently due to missing dependencies (like tkinter)

Solution 1: Run from Terminal (Quick Debug)

Run the existing app from terminal to see errors:

./run_app_debug.sh

Or manually:

"/Users/justinaspetravicius/Public/Gitea/path-juggler/dist/Path Juggler.app/Contents/MacOS/Path Juggler"

This will show you any error messages in the terminal.

Solution 2: Build Debug Version

Build a version with console output enabled:

./build_app_debug.sh

This creates Path Juggler Debug.app which will show a terminal window with all output.

Solution 3: Check System Logs

On macOS, you can also check system logs:

# View recent logs for the app
log show --predicate 'process == "Path Juggler"' --last 5m

# Or use Console.app (GUI)
open -a Console

Common Issues Found

Issue: Missing tkinter

Error: ModuleNotFoundError: No module named 'tkinter' or ModuleNotFoundError: No module named '_tkinter'

Root Cause: The build scripts now use uv to install Python 3.12, which includes tkinter by default. If you still see this error, it may be a PyInstaller bundling issue.

Fix: The build scripts use uv to:

1. Install Python 3.12 (which has tkinter built-in)
2. Create a virtual environment with that Python
3. Install all dependencies
4. Build with PyInstaller (which bundles everything including tkinter)

Rebuild the app:

./build_app.sh

If tkinter is still missing:

1. Make sure uv is installed: brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh
2. The build script will automatically download Python 3.12 if needed
3. PyInstaller should bundle tkinter automatically - if not, check the PyInstaller output for warnings

Issue: Missing watchdog modules

Error: ModuleNotFoundError: No module named 'watchdog.observers.fsevents'

Fix: Make sure watchdog is installed in the build environment. The build script handles this automatically.

Rebuilding After Fixes

After fixing issues, rebuild:

# Production build (no console)
./build_app.sh

# Debug build (with console)
./build_app_debug.sh

Testing the Fix

After rebuilding, test:

1. Quick test from terminal:

   ./run_app_debug.sh
   

2. Or launch the debug version:

   open "dist/Path Juggler Debug.app"
   

3. Or launch the production version:

   open "dist/Path Juggler.app"
   

Current Status

The build scripts have been updated to include tkinter in the hidden imports. You should rebuild the app to apply the fix.