# Build Notes

## Build Status

✅ **macOS Build: SUCCESS**
- Built on: macOS 15.6 (arm64)
- Python Version: 3.9.6 (Xcode system Python with tkinter support)
- Output: `dist/ESP32_Flasher.app`
- Size: ~7.0 MB
- Tested: ✅ Application launches and runs successfully

## Prerequisites

### macOS
**Important:** Homebrew's Python 3.13 does NOT include tkinter support by default.

**Solution:** Install python-tk package:
```bash
brew install python-tk@3.13
```

However, the build system will automatically use the system Python (3.9.6 from Xcode) which has tkinter built-in. This is the recommended approach.

## Known Issues

### ~~macOS tkinter Warning~~ - RESOLVED
**Previous Issue:** Homebrew Python 3.13 doesn't include tkinter
**Solution:** Build system now uses Xcode's Python 3.9.6 which has native tkinter support
**Status:** ✅ Fixed - no warnings, app works perfectly

### Virtual Environment Required (macOS)
Due to PEP 668 (externally-managed environments), macOS requires using a virtual environment for pip installations. The build scripts automatically handle this.

## Build Commands

### Quick Build (Any Platform)
```bash
python3 build.py
```

### macOS Specific
```bash
./build_macos.sh
```
or
```bash
source venv/bin/activate
pyinstaller ESP32_Flasher_macOS.spec
```

### Windows Specific
```batch
build_from_spec.bat
```

## Distribution

### macOS
- Distribute the entire `ESP32_Flasher.app` folder (it's a bundle)
- Users may need to run: `xattr -cr ESP32_Flasher.app` if macOS blocks it
- Consider creating a DMG for easier distribution

### Windows
- Distribute the single `ESP32_Flasher.exe` file
- No installation required
- May trigger Windows SmartScreen (normal for unsigned apps)

## File Structure

```
flash_tool/
├── dist/                          # Build output
│   ├── ESP32_Flasher.app         # macOS bundle
│   └── ESP32_Flasher             # Standalone binary
├── build/                         # Build artifacts
├── venv/                          # Python virtual environment (macOS)
├── gui_flasher.py                # Source code
├── ESP32_Flasher_macOS.spec      # macOS build config
├── ESP32_Flasher_Windows.spec    # Windows build config
├── build.py                      # Universal build script
├── build_macos.sh                # macOS build script
└── build_from_spec.bat           # Windows build script
```

## Next Steps

1. **Testing**: Test the app with actual ESP32 hardware and firmware
2. **Icons**: Add custom icons (.icns for macOS, .ico for Windows)
3. **Code Signing**: Sign the executables for production distribution
4. **DMG Creation**: Package macOS app in a DMG for easier distribution
5. **Windows Installer**: Consider creating an NSIS or WiX installer

## Troubleshooting

### "App is damaged" on macOS
```bash
xattr -cr dist/ESP32_Flasher.app
```

### Port permission issues on Linux
```bash
sudo usermod -a -G dialout $USER
```
(Logout/login required)

### Build fails on macOS
Make sure virtual environment is active:
```bash
source venv/bin/activate
```