111 lines
3.1 KiB
Markdown
111 lines
3.1 KiB
Markdown
# 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
|
|
```
|