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:

Development environment

Complete the development setup first, including:

Python 3.10+

All dependencies from requirements.txt

Dictionary file (jmdict_enhanced.pkl)

Verify the app works

Test that meikipop runs correctly from source:

python -m src.main

Make sure you can:

See the system tray icon

Trigger OCR with the hotkey

See dictionary popups

Running from source

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

python -m src.main
pause

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

Open terminal in project directory

Navigate to the meikipop root folder.

Run PyInstaller with the spec file

pyinstaller meikipop.win.x64.spec

This creates:

build/ - Temporary build files

dist/meikipop.exe - The final executable

Copy required data files

The executable needs the dictionary file:

# Create a distribution folder
mkdir meikipop-windows-x64
copy dist\meikipop.exe meikipop-windows-x64\
mkdir meikipop-windows-x64\data
copy data\jmdict_enhanced.pkl meikipop-windows-x64\data\

Test the executable

cd meikipop-windows-x64
meikipop.exe

Open terminal in project directory

Navigate to the meikipop root folder.

Run PyInstaller with the spec file

pyinstaller meikipop.linux.x64.spec

This creates:

build/ - Temporary build files

dist/meikipop - The final executable

Copy required data files

The executable needs the dictionary file:

# Create a distribution folder
mkdir -p meikipop-linux-x64/data
cp dist/meikipop meikipop-linux-x64/
cp data/jmdict_enhanced.pkl meikipop-linux-x64/data/
chmod +x meikipop-linux-x64/meikipop

Test the executable

cd meikipop-linux-x64
./meikipop

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:

Enable UPX compression

UPX is already enabled in the spec files:

upx=True,
upx_exclude=[],

Install UPX for your platform:

Windows: Download from upx.github.io and add to PATH

Linux: sudo apt-get install upx or sudo pacman -S upx

Exclude unnecessary modules

Add to the excludes list in your spec file:

excludes=['tkinter', 'matplotlib', 'numpy', 'scipy'],

Remove unused OCR providers

If you only need specific OCR providers, remove unused ones from:

datas=[] list

hiddenimports=[] list

src/ocr/providers/ directory

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:

Add provider files to datas

datas=[
    # Your custom provider
    ('src/ocr/providers/myprovider/provider.py', 'src/ocr/providers/myprovider'),
    ('src/ocr/providers/myprovider/__init__.py', 'src/ocr/providers/myprovider'),
],

Add to hiddenimports

hiddenimports=['src.ocr.providers.myprovider'],

Include provider dependencies

If your provider has external dependencies (models, configs), add them:

datas=[
    ('src/ocr/providers/myprovider/model.onnx', 'src/ocr/providers/myprovider'),
],

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

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

Build docs developers (and LLMs) love

Custom OCR Providers

Contributing

Documentation Index

​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

Build docs developers (and LLMs) love

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