> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/rtr46/meikipop/llms.txt
> Use this file to discover all available pages before exploring further.

# Development setup

> Set up your local development environment for meikipop

This guide walks you through setting up a development environment for meikipop on Windows, Linux, and macOS.

## Prerequisites

Before you begin, make sure you have the following installed:

<Steps>
  ### Python 3.10 or higher

  Meikipop requires Python 3.10+. Verify your installation:

  ```bash theme={null}
  python --version
  # or on some systems
  python3 --version
  ```

  ### Git (optional but recommended)

  For cloning the repository and version control:

  ```bash theme={null}
  git --version
  ```

  ### Platform-specific requirements

  <Tabs>
    <Tab title="Windows">
      No additional system requirements. Python packages will handle everything.
    </Tab>

    <Tab title="Linux (X11)">
      Make sure you're running X11 (not Wayland). Meikipop uses X11-specific APIs for keyboard monitoring.

      ```bash theme={null}
      # Verify you're using X11
      echo $XDG_SESSION_TYPE
      # Should output: x11
      ```

      You'll also need development headers:

      ```bash theme={null}
      # Debian/Ubuntu
      sudo apt-get install python3-dev libx11-dev

      # Fedora
      sudo dnf install python3-devel libX11-devel

      # Arch
      sudo pacman -S python libx11
      ```
    </Tab>

    <Tab title="macOS">
      <Warning>
        Meikipop support on macOS is currently in beta. The system tray may not work reliably, and you may need to configure settings via `config.ini` directly.
      </Warning>

      You'll need to grant permissions for meikipop to work:

      1. Open **System Preferences** → **Security & Privacy** → **Privacy**
      2. Add your terminal app (Terminal.app, iTerm2, etc.) to:
         * **Input Monitoring**
         * **Screen Recording**
         * **Accessibility**

      You may need to restart your terminal after granting permissions.
    </Tab>
  </Tabs>
</Steps>

## Clone the repository

Get the latest source code from GitHub:

```bash theme={null}
git clone https://github.com/rtr46/meikipop.git
cd meikipop
```

Alternatively, download the source archive:

```bash theme={null}
# Download and extract
wget https://github.com/rtr46/meikipop/archive/refs/heads/main.zip
unzip main.zip
cd meikipop-main
```

## Set up virtual environment (recommended)

Using a virtual environment keeps your dependencies isolated:

<CodeGroup>
  ```bash Windows (cmd) theme={null}
  python -m venv venv
  venv\Scripts\activate
  ```

  ```bash Windows (PowerShell) theme={null}
  python -m venv venv
  .\venv\Scripts\Activate.ps1
  ```

  ```bash Linux/macOS theme={null}
  python3 -m venv venv
  source venv/bin/activate
  ```
</CodeGroup>

You should see `(venv)` in your terminal prompt when the environment is active.

## Install dependencies

Install all required Python packages from `requirements.txt`:

```bash theme={null}
pip install -r requirements.txt
```

### Understanding the dependencies

Here are the key dependencies (from `requirements.txt`):

```txt theme={null}
PyQt6>=6.9.1              # GUI framework for popup and tray icon
pynput>=1.7.8              # Cross-platform mouse control
mss>=10.0.0                # Fast screenshot capture
requests>=2.32.4           # HTTP client for OCR APIs
Pillow>=11.2.1             # Image processing
betterproto>=2.0.0b7       # Protocol buffers for Google Lens
protobuf>=6.33.1           # Protocol buffer runtime
websockets>=15.0.1         # WebSocket support for owocr
meikiocr>=0.3.1            # Local OCR provider

# Platform-specific dependencies
keyboard~=0.13.5; sys_platform == 'win32'                # Windows keyboard input
pyobjc-framework-Quartz>=10.0; sys_platform == 'darwin'  # macOS screen APIs
pyobjc-framework-Cocoa>=10.0; sys_platform == 'darwin'   # macOS UI APIs
python-xlib~=0.33; sys_platform == 'linux'               # Linux X11 APIs
onnxruntime==1.20.1; sys_platform == 'win32'            # Pinned for Windows stability
```

<Note>
  Platform-specific dependencies are automatically installed only on the relevant operating system.
</Note>

## Build the dictionary

Meikipop requires a preprocessed dictionary file for fast lookups. You have two options:

### Option 1: Download prebuilt dictionary (faster)

Download `jmdict_enhanced.pkl` from the latest release:

```bash theme={null}
# Download from releases page
wget https://github.com/rtr46/meikipop/releases/latest/download/data.zip
unzip data.zip
# This extracts jmdict_enhanced.pkl to the data/ directory
```

### Option 2: Build from source (requires lxml)

Build the dictionary yourself:

<Steps>
  ### Install build dependencies

  ```bash theme={null}
  pip install lxml
  ```

  ### Run the build script

  ```bash theme={null}
  python -m scripts.build_dictionary
  ```

  This downloads the latest JMdict XML data and processes it into the optimized `.pkl` format.

  <Info>
    Building the dictionary can take several minutes depending on your system.
  </Info>
</Steps>

## Verify your setup

Ensure everything is configured correctly:

<Steps>
  ### Check directory structure

  Your project should look like this:

  ```
  meikipop/
  ├── data/
  │   └── jmdict_enhanced.pkl    # Dictionary file (required)
  ├── src/
  │   ├── main.py                # Entry point
  │   ├── config/
  │   ├── dictionary/
  │   ├── gui/
  │   ├── ocr/
  │   ├── screenshot/
  │   └── utils/
  ├── requirements.txt
  └── config.ini                  # Created on first run
  ```

  ### Run meikipop

  ```bash theme={null}
  python -m src.main
  ```

  You should see output like:

  ```
  --------------------------------------------------
  meikipop.0.x.x is running in the background.

    - To use: Press and hold 'shift' over Japanese text.
    - To configure or change scan area: Right-click the icon in your system tray.
    - Make sure to checkout the auto scan mode!
    - To exit: Press Ctrl+C in this terminal.

  --------------------------------------------------
  ```

  ### Test basic functionality

  1. The app should prompt you to select a scan region (first run only)
  2. A system tray icon should appear
  3. Position some Japanese text on your screen
  4. Hold the hotkey (Shift by default) and hover over the text
  5. A popup with dictionary entries should appear
</Steps>

## Development workflow

### Running from source

Always run meikipop as a module:

```bash theme={null}
python -m src.main
```

<Warning>
  Do not run `python src/main.py` directly. This breaks relative imports within the application.
</Warning>

### Configuration file

Settings are stored in `config.ini` in the project root:

```ini theme={null}
[settings]
hotkey = shift
ocr_provider = Google Lens v2
scan_region = region
auto_scan_mode = False
font_family = MS Gothic
color_background = #1e1e1e
# ... and more
```

Changes via the GUI are saved automatically. You can also edit this file directly.

### Logging

Meikipop outputs debug information to the console. To see more detailed logs, modify `src/utils/logger.py`.

### Code style

The codebase generally follows PEP 8. Key conventions:

* Snake\_case for functions and variables
* PascalCase for classes
* Module-level constants in UPPER\_CASE
* Descriptive variable names (e.g., `hit_scan_result` not `hsr`)

## Troubleshooting

<AccordionGroup>
  <Accordion title="ImportError: No module named 'src'">
    You're running the script incorrectly. Always use:

    ```bash theme={null}
    python -m src.main
    ```

    Not:

    ```bash theme={null}
    python src/main.py  # Wrong!
    ```
  </Accordion>

  <Accordion title="ModuleNotFoundError: No module named 'PyQt6'">
    Dependencies aren't installed. Run:

    ```bash theme={null}
    pip install -r requirements.txt
    ```
  </Accordion>

  <Accordion title="RuntimeError: Failed to load dictionary">
    The `jmdict_enhanced.pkl` file is missing from the `data/` directory. See [Build the dictionary](#build-the-dictionary) section.
  </Accordion>

  <Accordion title="Linux: Could not connect to X server">
    You're either:

    * Not running X11 (check with `echo $XDG_SESSION_TYPE`)
    * Missing the DISPLAY environment variable
    * Running without a graphical session

    Meikipop requires a graphical X11 session to function.
  </Accordion>

  <Accordion title="macOS: Keyboard hotkey not working">
    Make sure you've granted Input Monitoring permissions to your terminal app in **System Preferences** → **Security & Privacy** → **Privacy** → **Input Monitoring**.

    You may need to restart the terminal after granting permissions.
  </Accordion>

  <Accordion title="Windows: The 'keyboard' library failed to import">
    On Windows, the keyboard library sometimes requires administrator privileges. Try running your terminal as administrator.
  </Accordion>
</AccordionGroup>

## Next steps

Now that your environment is set up, you can:

* [Learn about the architecture](/development/architecture) to understand how meikipop works
* [Build executables](/development/building-from-source) with PyInstaller
* Start contributing by fixing bugs or adding features

<Tip>
  Join the discussion on GitHub Issues if you need help or want to propose changes to meikipop.
</Tip>