Building from source

This guide covers the complete process of building meikipop from source, including creating standalone executables for distribution.

Prerequisites

Before building, ensure you have:

Running from source

For development and testing, always run meikipop as a module:

python -m src.main
pause

python3 -m src.main

The project includes convenience scripts:

meikipop.run.bat (Windows) - Runs from source
meikipop.install.bat (Windows) - Installs dependencies

Building executables with PyInstaller

Meikipop uses PyInstaller to create standalone executables that bundle Python and all dependencies into a single file.

Install PyInstaller

pip install pyinstaller

Understanding the spec files

Meikipop includes platform-specific PyInstaller spec files that configure the build process:

meikipop.win.x64.spec - Windows 64-bit
meikipop.linux.x64.spec - Linux 64-bit

Windows spec file breakdown

Here’s the meikipop.win.x64.spec configuration:

a = Analysis(
    ['src\\main.py'],              # Entry point
    pathex=[],
    binaries=[],
    datas=[
        # OCR provider modules (dynamically loaded)
        ('src/ocr/providers/glensv2/provider.py', 'src/ocr/providers/glensv2'),
        ('src/ocr/providers/owocr/provider.py', 'src/ocr/providers/owocr'),
        ('src/ocr/providers/meikiocr/provider.py', 'src/ocr/providers/meikiocr'),
        ('src/ocr/providers/screenai/provider.py', 'src/ocr/providers/screenai'),
        # ... (supporting files for each provider)
        
        # Application icons
        ('src/resources/icon.ico', '.'),
        ('src/resources/icon.ico', 'src/resources'),
        ('src/resources/icon.inactive.ico', '.'),
        ('src/resources/icon.inactive.ico', 'src/resources'),
    ],
    hiddenimports=[
        'src.ocr.providers.glensv2',
        'src.ocr.providers.owocr',
        'src.ocr.providers.meikiocr',
        'src.ocr.providers.screenai'
    ],
    # ... other settings
)

OCR providers are included as data files because they’re discovered dynamically at runtime using importlib. Without explicit inclusion, PyInstaller would miss them.

Executable configuration

exe = EXE(
    pyz,
    a.scripts,
    a.binaries,
    a.datas,
    [],
    name='meikipop',               # Output filename
    debug=False,                    # No debug console
    bootloader_ignore_signals=False,
    strip=False,                    # Don't strip symbols
    upx=True,                       # Compress with UPX
    upx_exclude=[],
    icon='src\\resources\\icon.ico',  # Executable icon
    runtime_tmpdir=None,
    console=True,                   # Show console window (for logging)
    # ... other settings
)

Build process

Windows
Linux
macOS

There’s currently no official macOS spec file. macOS builds are experimental. You can adapt the Linux spec file, but expect issues with the system tray and permissions.

For macOS, it’s recommended to run from source:

python3 -m src.main

Distribution package structure

A complete distribution should include:

meikipop-{platform}-x64/
├── meikipop.exe (or meikipop)    # The executable
├── data/
│   └── jmdict_enhanced.pkl        # Dictionary (required!)
├── README.txt                     # Usage instructions
└── LICENSE                        # GPL v3.0 license

The executable will not work without jmdict_enhanced.pkl in the data/ subdirectory. The app will exit with “Failed to load dictionary” error.

Build optimization

Reducing executable size

The default build can be quite large (100+ MB). To optimize:

Troubleshooting builds

ImportError when running executable

A module wasn’t included in the build. Check:

Is it in hiddenimports in the spec file?
Are there any dynamically imported modules?

Add missing imports to hiddenimports:

hiddenimports=['missing.module.name'],

FileNotFoundError: icon.ico

Icons aren’t being bundled correctly. Verify the datas section includes:

datas=[
    ('src/resources/icon.ico', '.'),
    ('src/resources/icon.ico', 'src/resources'),
],

And ensure the icon files exist in src/resources/.

No OCR providers found!

OCR provider modules weren’t included as data files. The spec must include:

All .py files in datas list
Provider packages in hiddenimports list

See the Windows spec file for the complete list.

RuntimeError: Failed to load dictionary

The executable can’t find jmdict_enhanced.pkl. Make sure:

The data/ folder exists next to the executable
jmdict_enhanced.pkl is inside data/
The file has read permissions

Executable crashes on startup (Windows)

Common causes:

ONNX runtime version mismatch (pinned to 1.20.1 for Windows)
Missing Visual C++ Redistributables

Try:

# Reinstall onnxruntime
pip uninstall onnxruntime
pip install onnxruntime==1.20.1

# Rebuild
pyinstaller --clean meikipop.win.x64.spec

Linux: error while loading shared libraries

The executable was built on a system with different library versions. PyInstaller bundles libraries, but sometimes they conflict.Solutions:

Build on the oldest Linux version you want to support
Or build in a Docker container with specific library versions

Advanced: Custom builds

Adding custom OCR providers

If you’ve created a custom OCR provider, include it in the build:

Building with debug logging

For troubleshooting, enable console output:

exe = EXE(
    # ...
    console=True,      # Keep console window open
    debug=True,        # Enable debug output
    # ...
)

Creating distributable archives

Once you have a working build, create an archive for distribution:

# Create a ZIP archive
tar -a -c -f meikipop-windows-x64.zip meikipop-windows-x64

# Create a tarball
tar -czf meikipop-linux-x64.tar.gz meikipop-linux-x64/

Next steps

After building:

Test on a clean system without Python installed
Verify all OCR providers work
Check the system tray and settings dialog
Test with different hotkey configurations
Distribute to users!

For official releases, builds should be created on GitHub Actions to ensure reproducibility and consistency across platforms.

Custom OCR Providers

Contributing

Building from source

Prerequisites

Running from source

Building executables with PyInstaller

Install PyInstaller

Understanding the spec files

Windows spec file breakdown

Executable configuration

Build process

Distribution package structure

Build optimization

Reducing executable size

Troubleshooting builds

Advanced: Custom builds

Adding custom OCR providers

Building with debug logging

Creating distributable archives

Next steps

​Prerequisites

​Running from source

​Building executables with PyInstaller

​Install PyInstaller

​Understanding the spec files

​Windows spec file breakdown

​Executable configuration

​Build process

​Distribution package structure

​Build optimization

​Reducing executable size

​Troubleshooting builds

​Advanced: Custom builds

​Adding custom OCR providers

​Building with debug logging

​Creating distributable archives

​Next steps

Prerequisites

Running from source

Building executables with PyInstaller

Install PyInstaller

Understanding the spec files

Windows spec file breakdown

Executable configuration

Build process

Distribution package structure

Build optimization

Reducing executable size

Troubleshooting builds

Advanced: Custom builds

Adding custom OCR providers

Building with debug logging

Creating distributable archives

Next steps