adaptronic_label-printer/BUILD_EXECUTABLE.md

# Build Windows Executable (.exe)

## Quick Start

**Option 1: One Command (Recommended)**
```bash
build_windows.bat
```

**Option 2: Python Script**
```bash
python build_exe.py
```

**Option 3: Direct PyInstaller**
```bash
pyinstaller LabelPrinter.spec
```

---

## Requirements

- **Windows** 10/11
- **Python** 3.10 - 3.13 (Python 3.14+ may have compatibility issues)
- **Dependencies** installed (see below)

---

## Step-by-Step Build Process

### 1. Install Python Dependencies

If not already installed:
```bash
pip install -r requirements_windows.txt
```

Or install manually:
```bash
pip install python-barcode pillow reportlab kivy==2.2.1 pyinstaller==6.1.0 pywin32 wmi watchdog svglib cairosvg
```

### 2. Build the Executable

Run the build script:
```bash
build_windows.bat
```

This will:
- ✅ Install/upgrade dependencies
- ✅ Clean old build artifacts
- ✅ Create `LabelPrinter.exe` in `dist/` folder
- ⏱️ Takes 5-15 minutes

### 3. Test the Executable

```bash
cd dist
LabelPrinter.exe
```

---

## What Gets Included

The executable is **self-contained** and includes:
- ✅ All Python code
- ✅ All dependencies (Kivy, ReportLab, svglib, cairosvg, etc.)
- ✅ Auto-generates `conf/` folder on first run
- ✅ Auto-generates `pdf_backup/` and `logs/` folders

**On first run, the app automatically creates:**
```
LabelPrinter.exe location/
├── conf/
│   ├── app.conf                    (default settings)
│   ├── label_template.svg          (default template)
│   ├── label_template_ok.svg       (OK labels - green)
│   └── label_template_nok.svg      (NOK labels - red)
├── pdf_backup/                     (generated PDFs)
└── logs/                           (print logs)
```

---

## Output

After successful build:

```
📁 dist/
   └── LabelPrinter.exe  (Single file, ~80-120 MB)
```

**File size**: 80-120 MB (includes Python runtime + all libraries)

---

## Distribution

### To Deploy on Other Windows Machines:

**Simply copy `LabelPrinter.exe` to the target machine!**

The executable is **100% self-contained**:
- ✅ No Python installation needed
- ✅ No dependencies needed  
- ✅ Auto-creates all required folders on first run
- ✅ Generates default templates automatically

**First run will create:**
```
[wherever you put LabelPrinter.exe]/
├── LabelPrinter.exe               ← Copy just this file!
├── conf/                          ← Auto-generated on first run
│   ├── app.conf
│   ├── label_template.svg
│   ├── label_template_ok.svg
│   └── label_template_nok.svg
├── pdf_backup/                    ← Auto-generated
└── logs/                          ← Auto-generated
```

**To customize templates on target machine:**
1. Run `LabelPrinter.exe` once (generates conf folder)
2. Edit SVG files in the `conf/` folder
3. Restart the application

**Requirements on target machine:**
- ✅ Windows 10/11
- ✅ Thermal printer configured (35mm x 25mm paper size)
- ⚠️ No other software required!

---

## Troubleshooting

### Build Fails - Missing Dependencies
```bash
pip install --upgrade pip setuptools wheel
pip install -r requirements_windows.txt
```

### Build Fails - PyInstaller Error
```bash
pip install --upgrade pyinstaller==6.1.0
```

### Executable Won't Start
- Check Windows Defender didn't quarantine it
- Run as Administrator once to register
- Check Event Viewer for errors

### Executable is Huge (>150 MB)
This is normal! It includes:
- Python runtime (~40 MB)
- Kivy framework (~30 MB)
- ReportLab, PIL, etc. (~20 MB)
- Your code + data (~10 MB)

### First Run is Slow
- First launch takes 10-30 seconds (Kivy initialization)
- Subsequent launches are faster (~2-5 seconds)
- This is normal behavior

---

## Advanced Options

### Build with Console (for debugging)
Edit `build_windows.bat` and remove `--windowed`:
```bat
pyinstaller label_printer_gui.py ^
    --onefile ^
    --name=LabelPrinter ^
    ...
```

### Add Custom Icon
```bat
pyinstaller label_printer_gui.py ^
    --onefile ^
    --windowed ^
    --icon=icon.ico ^
    ...
```

### Reduce File Size
Not recommended, but possible:
```bat
pyinstaller label_printer_gui.py ^
    --onefile ^
    --windowed ^
    --strip ^
    --exclude-module=tkinter ^
    --exclude-module=matplotlib ^
    ...
```

---

## What's Built

**Source Files Compiled:**
- `label_printer_gui.py` (Main GUI)
- `print_label.py` (Printing logic)
- `print_label_pdf.py` (PDF generation)

**Data Files Included:**
- `conf/app.conf` (Settings)
- `conf/label_template.svg` (Default template)
- `conf/label_template_ok.svg` (OK labels - green)
- `conf/label_template_nok.svg` (NOK labels - red)
- `conf/accepted.png` (Checkmark image)

**Output Folders:**
- `pdf_backup/` - Stores generated PDFs
- `logs/` - Stores print logs

---

## Build Times

- **First build**: 10-15 minutes (PyInstaller analyzes all dependencies)
- **Rebuild**: 5-10 minutes (cached analysis)
- **Clean build**: 10-15 minutes (removed cache)

---

## File Structure After Build

```
📁 Project Root/
├── 📄 label_printer_gui.py
├── 📄 print_label.py
├── 📄 print_label_pdf.py
├── 📄 build_windows.bat        ← Run this
├── 📄 build_exe.py
├── 📄 LabelPrinter.spec
│
├── 📁 dist/
│   ├── 📄 LabelPrinter.exe     ← Your executable!
│   ├── 📁 conf/
│   ├── 📁 pdf_backup/
│   └── 📁 logs/
│
├── 📁 build/                    (temp files, can delete)
└── 📁 conf/
    ├── app.conf
    ├── label_template.svg
    ├── label_template_ok.svg
    └── label_template_nok.svg
```

---

## Clean Build

To remove all build artifacts:
```bash
rmdir /s /q build
rmdir /s /q dist
del *.spec
```

Then rebuild:
```bash
build_windows.bat
```

---

## Testing

After building, test with:

1. **Run the executable**:
   ```bash
   dist\LabelPrinter.exe
   ```

2. **Configure monitoring**:
   - File: `C:\Users\Public\Documents\check.txt`

3. **Test print**:
   - Add to check.txt: `COM-001;ART-123;SN-001;0;1`
   - Should print 1 OK label

4. **Test template switching**:
   - `COM-002;ART-456;SN-002;1;1` → NOK label (red)

---

## Support

If build fails, check:
1. Python version (3.10-3.13 required)
2. All dependencies installed
3. Windows 10/11 (not Windows 7/8)
4. Disk space (need ~500MB for build)
5. Antivirus not blocking PyInstaller