Building Wareflow EMS Standalone Executables

This guide explains how to build standalone executables for Wareflow Employee Management System that don't require Python installation.

Overview

Wareflow EMS can be distributed as standalone executables using PyInstaller. These executables bundle all dependencies and can run on any system without requiring Python installation.

Available Builds

GUI Version (wems): Full-featured desktop application with CustomTkinter GUI
CLI Version (wems-cli): Command-line interface for automation and scripting

Supported Platforms

Windows 10/11: .exe executable
Linux (Ubuntu 20.04+, Debian 11+): Binary executable
macOS: (Coming soon - pending code signing setup)

Prerequisites

Required Tools

Python 3.14+ (for building only, not required for running the executable)
uv - Fast Python package installer
```
pip install uv
```
PyInstaller - Bundling tool
```
uv pip install pyinstaller
```

System Requirements for Building

Windows: Windows 10 or later with Visual C++ Redistributable
Linux: Build essentials (gcc, g++, make)
Disk Space: ~500 MB for dependencies and build artifacts

Quick Start

Clone and Setup

# Clone the repository
git clone https://github.com/wareflowx/wareflow-ems.git
cd wareflow-ems

# Install dependencies
uv sync --dev

# Install PyInstaller
uv pip install pyinstaller

Build Executables

# Build GUI version (default)
python build/build.py

# Build CLI version
python build/build.py --cli

# Build both versions
python build/build.py --all

# Clean build (removes old artifacts)
python build/build.py --clean

# Skip tests (faster for development)
python build/build.py --skip-tests

Build Artifacts

Built executables are located in dist/:

dist/
├── wems/
│   ├── wems.exe              # Windows GUI executable
│   └── [supporting files]
├── wems-cli/
│   ├── wems-cli.exe          # Windows CLI executable
│   └── [supporting files]
├── wems-version.txt          # Version info
└── wems-cli-version.txt      # Version info

Detailed Build Options

GUI Build

python build/build.py

Creates a GUI application with:

CustomTkinter interface
Full feature set
No console window
Double-click to run

Output: dist/wems/wems.exe (Windows) or dist/wems/wems (Linux)

CLI Build

python build/build.py --cli

Creates a command-line application with:

All CLI commands
Works in terminals
Smaller file size
Scriptable

Output: dist/wems-cli/wems-cli.exe (Windows) or dist/wems-cli/wems-cli (Linux)

Build Both Versions

python build/build.py --all

Builds both GUI and CLI versions in sequence.

Clean Build

python build/build.py --clean

Removes all build artifacts before building, ensuring a fresh build.

Specify Version

python build/build.py --version 1.2.3

Overrides the automatic version detection.

Build Spec Files

wems.spec (GUI)

Configuration for the GUI executable:

Entry point: src/main.py
Includes: CustomTkinter, GUI modules, all dependencies
Windowed: No console shown
Icon: build/assets/icon.ico

wems-cli.spec (CLI)

Configuration for the CLI executable:

Entry point: src/cli_main.py
Includes: CLI modules, excludes GUI frameworks
Console: Shows terminal output
Smaller size: GUI modules excluded

Verification

Checksums

Each build generates SHA256 checksums:

# Windows
certutil -hashify SHA256 dist/wems/wems.exe

# Linux
sha256sum dist/wems/wems

Checksums are saved as dist/wems.exe.sha256 for verification.

Version Info

Version information is injected during build:

cat dist/wems-version.txt

Output:

Wareflow Employee Management System
Version: 1.2.3
Build Type: GUI
Build Date: 2025-01-23T12:00:00
Platform: win32
Python: 3.14.2

Testing Builds

Quick Smoke Test

# Windows
dist\wems\wems.exe

# Linux
chmod +x dist/wems/wems
./dist/wems/wems

Test CLI Commands

# Windows
dist\wems-cli\wems-cli.exe --help

# Linux
chmod +x dist/wems-cli/wems-cli
./dist/wems-cli/wems-cli --help

Test GUI Functionality

Launch the executable
Verify main window opens
Try adding an employee
Check database operations
Test Excel import/export

Distribution

Preparing for Release

Run full build:
```
python build/build.py --all --clean
```

Verify checksums:

cat dist/wems/*.sha256
cat dist/wems-cli/*.sha256

Test on clean system:
- Copy to a machine without Python
- Verify it runs correctly
- Test all major features

Package for distribution:

# Create release package
mkdir release
cp dist/wems/wems.exe release/
cp dist/wems-cli/wems-cli.exe release/
cat dist/wems/*.sha256 > release/checksums.txt
cat dist/wems-cli/*.sha256 >> release/checksums.txt
cp README.md release/
cp LICENSE release/

GitHub Releases

Automated builds via GitHub Actions:

Push a tag:
```
git tag v1.2.3
git push origin v1.2.3
```
GitHub Actions automatically:
- Builds executables for all platforms
- Runs tests
- Generates checksums
- Creates GitHub Release
- Uploads artifacts

Download from:

https://github.com/wareflowx/wareflow-ems/releases

Troubleshooting

Build Fails

Issue: ModuleNotFoundError: No module named 'customtkinter'

Solution:

uv sync
uv pip install customtkinter

Issue: ImportError: DLL load failed

Solution: Install Visual C++ Redistributable:

Download from Microsoft
Install and restart

Issue: Icon not found

Solution:

python build/create_icon.py

Executable Won't Run

Issue: Double-clicking does nothing

Solution: Run from command line to see error:

# Windows
cd dist\wems
wems.exe

# Linux
cd dist/wems
./wems

Issue: "Application failed to start"

Solution:

Verify all supporting files are present
Check antivirus isn't blocking it
Try running as administrator

Issue: Database errors

Solution:

Ensure data directory exists
Check file permissions
Verify database isn't corrupted

File Size Issues

Issue: Executable is too large (> 150 MB)

Solution:

Check what's included in the spec file
Add more packages to excludes list
Use UPX compression (enabled by default)
Consider one-file vs directory build

Issue: Executable is too small (< 20 MB)

Solution:

Something likely failed during build
Check build logs for errors
Verify all dependencies were bundled

Platform-Specific Issues

Windows

SmartScreen Warning: Windows shows "Unrecognized app" warning

Solution: This is expected for unsigned executables. Users need to click "More info" → "Run anyway".

Antivirus Blocks: Antivirus software flags the executable

Solution:

Add to antivirus exclusions
Submit to Microsoft SmartScreen for whitelist
Sign the executable (code signing certificate required)

Linux

Permission Denied: Can't execute the binary

Solution:

chmod +x dist/wems/wems

Missing Libraries: Error about missing .so files

Solution:

# Install missing dependencies
sudo apt-get install libxcb-xinerama0 libxcb-cursor0

macOS

Gatekeeper Blocks: "can't be opened because it is from an unidentified developer"

Solution: Code signing is required for distribution. This is not yet implemented.

Advanced Configuration

Customizing the Icon

Edit build/create_icon.py
Change colors, text, or design
Regenerate icons:
```
python build/create_icon.py
```

Modifying Spec Files

Edit build/wems.spec or build/wems-cli.spec:

Add hidden imports:

hiddenimports = [
    "your.module",
    "another.module",
]

Exclude packages:

excludes = [
    "unwanted.package",
]

Include data files:

datas = [
    ("path/to/data", "data"),
]

One-File Build

For a single-file executable (not recommended - slower startup):

In spec file, change:

exe = EXE(
    ...
    exclude_binaries=False,  # Changed from True
    ...
)

# Remove the COLLECT section

Compression

Enable UPX compression (enabled by default):

exe = EXE(
    ...
    upx=True,
    upx_exclude=[],
    ...
)

CI/CD Integration

The .github/workflows/build.yml workflow automatically builds executables on:

Git tags: Push v*.*.* tag to trigger build
Manual trigger: Use GitHub Actions "Run workflow" button

The workflow:

Builds on Windows and Linux
Runs tests
Generates checksums
Creates GitHub Release
Uploads artifacts

Performance Optimization

Reduce File Size

Exclude unused modules:

excludes = ["matplotlib", "numpy", "pandas"]

Use UPX compression: Enabled by default

Strip symbols:

exe = EXE(
    ...
    strip=True,
    ...
)

Improve Startup Time

Use directory build instead of one-file
- One-file: Must unpack every run
- Directory: Faster startup
Optimize imports:
- Remove unused imports in source code
- Lazy load heavy modules

Best Practices

Always test on clean system
- Build on development machine
- Test on machine without Python
- Verify all features work
Version your builds
- Use semantic versioning
- Tag releases in git
- Keep build artifacts
Generate checksums
- Always provide SHA256 checksums
- Document in release notes
- Users can verify integrity
Keep builds reproducible
- Use same Python version
- Lock dependency versions
- Document build environment
Test before release
- Run full test suite
- Manual testing of GUI
- Test on target platforms

Support

For issues or questions:

Documentation: See docs/
GitHub Issues: Report a problem
Discussions: Ask a question

FilesExpand file tree

BUILD.md

Latest commit

History

BUILD.md

File metadata and controls

Building Wareflow EMS Standalone Executables

Overview

Available Builds

Supported Platforms

Prerequisites

Required Tools

System Requirements for Building

Quick Start

Clone and Setup

Build Executables

Build Artifacts

Detailed Build Options

GUI Build

CLI Build

Build Both Versions

Clean Build

Specify Version

Build Spec Files

wems.spec (GUI)

wems-cli.spec (CLI)

Verification

Checksums

Version Info

Testing Builds

Quick Smoke Test

Test CLI Commands

Test GUI Functionality

Distribution

Preparing for Release

GitHub Releases

Troubleshooting

Build Fails

Executable Won't Run

File Size Issues

Platform-Specific Issues

Windows

Linux

macOS

Advanced Configuration

Customizing the Icon

Modifying Spec Files

One-File Build

Compression

CI/CD Integration

Performance Optimization

Reduce File Size

Improve Startup Time

Best Practices

Support

Related Documentation