eboek.info-scraper/docs/BUILD_GUIDE.md

🏗️ Build Guide - Creating Executable Files

This guide explains how to compile the EBoek.info Scraper into standalone executable files for distribution.

📦 What You'll Get

• Single executable file (~30MB) containing everything needed
• No Python installation required on target machines
• All dependencies bundled (PyQt5, Selenium, etc.)
• Cross-platform support (Windows .exe, macOS app, Linux binary)

🚀 Quick Build

Option 1: Python Build Script (Recommended)

# Cross-platform automated build
python3 build_executable.py

Option 2: Platform-Specific Scripts

Windows:

build_exe.bat

macOS/Linux:

./build_exe.sh

Option 3: Manual PyInstaller

# Install PyInstaller
python3 -m pip install pyinstaller

# Build executable
python3 -m PyInstaller --onefile --windowed --name "EBoek_Scraper" gui_main.py

📋 Prerequisites

• Python 3.8+ with all project dependencies installed
• PyInstaller 6.0+ (auto-installed by build scripts)
• All project requirements (pip install -r requirements.txt)

🔧 Build Process Details

What Happens During Build:

1. Dependency Analysis - PyInstaller scans all imports
2. Code Compilation - Python code compiled to bytecode
3. Library Bundling - All dependencies packaged together
4. Executable Creation - Single-file output with launcher

Hidden Imports (Automatically Included):

• PyQt5 modules (QtCore, QtGui, QtWidgets)
• Selenium webdriver components
• Project modules (core/, gui/, utils/)

Excluded Modules (Size Optimization):

• tkinter, matplotlib, numpy, pandas (not needed)

📊 Build Results

Platform	Executable	Size	Location
Windows	EBoek_Scraper.exe	~30MB	dist/EBoek_Scraper.exe
macOS	EBoek_Scraper.app	~30MB	dist/EBoek_Scraper.app
Linux	EBoek_Scraper	~30MB	dist/EBoek_Scraper

💡 Platform Notes:

• Windows: PyInstaller automatically adds .exe extension when building on Windows
• macOS: Creates both .app bundle and Unix executable
• Cross-compilation: Build on target OS for best compatibility

🚀 Distribution

What to Share:

• Single file: The executable from dist/ folder
• No additional files needed - everything is bundled

First Run Instructions:

Windows Users:

1. Run EBoek_Scraper.exe
2. If Windows shows security warning:
   • Click "More Info"
   • Click "Run Anyway"
3. This only happens on first run

macOS Users:

1. Run EBoek_Scraper.app or EBoek_Scraper
2. If macOS shows security warning:
   • Right-click the file
   • Select "Open"
   • Click "Open" in dialog
3. This only happens on first run

Linux Users:

1. Make executable: chmod +x EBoek_Scraper
2. Run: ./EBoek_Scraper

🛠️ Advanced Build Options

Custom Spec File Build:

# Use custom spec file for advanced configuration
python3 -m PyInstaller eboek_scraper.spec

Debug Build:

# Build with console window for debugging
python3 -m PyInstaller --onefile --console gui_main.py

Directory Build (Faster startup):

# Build as directory instead of single file
python3 -m PyInstaller --onedir --windowed gui_main.py

🐛 Troubleshooting

Build Fails:

1. Check Python version: Must be 3.8+
2. Update PyInstaller: pip install --upgrade pyinstaller
3. Check dependencies: pip install -r requirements.txt
4. Try spec file: python3 -m PyInstaller eboek_scraper.spec

Executable Won't Run:

1. Check Chrome installation on target machine
2. Antivirus interference - add exception for scraper
3. Missing Visual C++ Redistributable (Windows only)

Large File Size:

1. Expected behavior - includes Python + PyQt5 + Selenium
2. Alternative: Use --onedir for faster startup
3. Size breakdown: Python(~15MB) + PyQt5(~10MB) + Selenium(~5MB)

📈 Performance Notes

• Startup time: 2-3 seconds (cold start)
• Memory usage: Similar to Python version
• Chrome requirement: Still needs Chrome browser installed
• No performance penalty once running

🔄 Updating Builds

When you update the source code:

1. Re-run build process to create new executable
2. Version number - consider adding to filename
3. Distribution - replace old executable with new one

💡 Tips

• Test executable on clean system before distribution
• Keep source code - executable is not easily reverse-engineered
• Build on target OS - Windows builds work best on Windows, etc.
• Sign executables (optional) to reduce security warnings

---

Happy building! 🚀