db_interface/BUILD_WINDOWS_GUIDE.md

Building Windows Executable with PyInstaller

Prerequisites

You need to build the executable on a Windows machine (PyInstaller creates platform-specific executables).

Step 1: Install PyInstaller

On Windows:

# Activate virtual environment
venv\Scripts\activate

# Install PyInstaller
pip install pyinstaller

Step 2: Build the Executable

Option A: Using the build script (Recommended)

python build_windows.py

Option B: Manual PyInstaller command

pyinstaller --name=DatabaseApp --onefile --windowed --hidden-import=mysql.connector --collect-all=kivy main.py

Step 3: Find Your Executable

After building, the executable will be in:

dist/DatabaseApp.exe

Step 4: Distribution

Copy the following to your target Windows machine:

• DatabaseApp.exe (from the dist folder)

That's it! The executable is fully standalone and doesn't require Python installation.

Advanced Build Options

Creating a Spec File for Customization

pyi-makespec --onefile --windowed main.py

Then edit main.spec and build:

pyinstaller main.spec

Adding an Application Icon

1. Get an .ico file (you can convert PNG to ICO online)
2. Save it as app_icon.ico in the project folder
3. Build with icon:

pyinstaller --name=DatabaseApp --onefile --windowed --icon=app_icon.ico --collect-all=kivy main.py

Troubleshooting

"Failed to execute script"

• Make sure all dependencies are included
• Try building with --onedir instead of --onefile for debugging:

  pyinstaller --name=DatabaseApp --onedir --windowed --collect-all=kivy main.py
  

Missing modules

Add hidden imports:

pyinstaller --name=DatabaseApp --onefile --windowed --hidden-import=module_name --collect-all=kivy main.py

Large executable size

This is normal for Kivy apps. Typical size: 50-100 MB To reduce size:

• Use --onedir instead of --onefile
• Use UPX compression: pip install pyinstaller[encryption]

Build Spec File (Advanced)

Create DatabaseApp.spec for more control:

# -*- mode: python ; coding: utf-8 -*-

block_cipher = None

a = Analysis(
    ['main.py'],
    pathex=[],
    binaries=[],
    datas=[('database_manager.py', '.')],
    hiddenimports=['mysql.connector', 'kivy'],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    win_no_prefer_redirects=False,
    win_private_assemblies=False,
    cipher=block_cipher,
    noarchive=False,
)

# Collect all Kivy dependencies
a.datas += Tree('venv/Lib/site-packages/kivy', prefix='kivy')

pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)

exe = EXE(
    pyz,
    a.scripts,
    a.binaries,
    a.zipfiles,
    a.datas,
    [],
    name='DatabaseApp',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    upx_exclude=[],
    runtime_tmpdir=None,
    console=False,  # No console window
    disable_windowed_traceback=False,
    argv_emulation=False,
    target_arch=None,
    codesign_identity=None,
    entitlements_file=None,
    icon='app_icon.ico'  # Optional
)

Then build:

pyinstaller DatabaseApp.spec

Testing the Executable

1. Copy DatabaseApp.exe to a test Windows machine without Python
2. Make sure MariaDB/MySQL is accessible (local or remote)
3. Run the executable
4. Use the Settings button to configure the database server IP if needed

Notes

• The executable size will be ~50-100 MB due to Kivy framework
• Build time: 2-5 minutes depending on your system
• The executable is completely standalone - no Python needed
• Database server must still be accessible (local or network)
• Settings are not persistent between runs (saved in memory only)

Creating an Installer (Optional)

Use Inno Setup to create a Windows installer:

1. Download Inno Setup: https://jrsoftware.org/isinfo.php
2. Create an installer script
3. Package DatabaseApp.exe with installer

This makes distribution even more professional.