# EMDS for QGIS — Linux Setup & Troubleshooting

> **Most users don't need this script.** Since plugin version 0.4.0 the
> plugin finishes its own setup: after *Install from ZIP*, click **Install
> now** in the dialog that appears (also under **Plugins → EMDS → Finish EMDS
> Setup…**)
> and restart QGIS. Use this script only when the in-app setup cannot run
> (offline or locked-down machines), or when you need the extras it doesn't
> cover (GDAL and libicu via apt).

After you install the **EMDS for QGIS** plugin, the script in this folder can
finish setting up your machine. Target: **Ubuntu 26.04** (other apt-based
distros should work; adjust package names as needed).

> **If you received a `EMDS_for_QGIS-<ver>-linux-x64-setup.zip`:** extract it to
> get two things — the QGIS plugin zip (`EMDS_for_QGIS-<ver>-linux-x64.zip`) and
> this script. First install the **plugin zip** in QGIS (Plugins → *Install from
> ZIP*), then run the script below to finish setup.

## What the script does

1. **GDAL** — ensure a usable `gdal` command-line tool (3.12+ with
   `gdal vector layer-algebra`), via `apt` and the **ubuntugis PPA** as a
   fallback. Required for full **Create Study Area** overlay processing.
2. **libicu** — install the native library the self-contained `.NET` engines
   need to start (usually already present on desktop Ubuntu; sometimes missing
   on minimal/server installs).
3. **Python packages** — install `pyarrow`, `pandas`, and `matplotlib` into the
   Python that QGIS uses (the system `python3`), preferring apt.
4. **Engine binaries** — mark the bundled engines (`NetWeaverCLI`, `CDPCLI`)
   executable. QGIS installs plugins by unzipping with Python's `zipfile`, which
   **strips the executable bit**, so the engines arrive non-executable.

> Unlike the macOS installer, there is **no PYTHONHOME repair** (Ubuntu's QGIS
> uses a normal system Python) and **no Gatekeeper/quarantine** handling (not a
> thing on Linux).

## Before you start

- Install **QGIS** — the [qgis.org apt repository](https://qgis.org/resources/installation-guide/#debian-ubuntu)
  build is recommended (a clean system `python3`; avoids snap/flatpak sandboxing).
- Install the **EMDS plugin ZIP**: QGIS → *Plugins* → *Manage and Install
  Plugins* → *Install from ZIP*.
- An **internet connection** and **sudo** access (for apt / the PPA).

## How to run

```bash
cd /path/to/this/folder
bash ./install-emds-runtime-deps.sh
```

To run unattended (no prompts; also passes `-y` to apt):

```bash
ASSUME_YES=1 bash ./install-emds-runtime-deps.sh
```

When it finishes, **restart QGIS** so it picks up the new packages, GDAL on
`PATH`, and the engine permissions.

## Options (environment variables)

Set before the command, e.g. `QGIS_PYTHON=/usr/bin/python3.12 bash ./install-emds-runtime-deps.sh`.

| Variable | Effect |
| --- | --- |
| `ASSUME_YES=1` | Don't prompt; pass `-y` to apt. |
| `QGIS_PYTHON` | The `python3` interpreter QGIS uses (default: `python3`). |
| `SKIP_GDAL=1` | Skip the GDAL check/install. |
| `SKIP_APT=1` | Never run apt (check only; use pip for Python packages). |
| `PYARROW_SPEC` / `PANDAS_SPEC` / `MATPLOTLIB_SPEC` | Override the version spec. |

## Troubleshooting

**"NetWeaver error … [Errno 13] Permission denied: '…/NetWeaverCLI'"** when you
start an analysis
The engine lost its executable bit (QGIS's ZIP install drops it). Re-run the
script, or fix it manually:
```bash
ENG="$HOME/.local/share/QGIS/QGIS4/profiles/default/python/plugins/emds_qgis_plugin/engines"
chmod +x "$ENG/linux-x64/NetWeaverCLI/NetWeaverCLI" "$ENG/linux-x64/CDPCLI/CDPCLI"
```

**The engine fails to start with a globalization / ICU error**
`libicu` is missing. Install it:
```bash
sudo apt install libicu-dev
```
(You can also force invariant globalization as a workaround, but installing ICU
is the correct fix.)

**Create Study Area overlay says GDAL is missing or too old**
Full overlays need GDAL 3.12+ with `gdal vector layer-algebra`. Verify:
```bash
gdal --version
gdal vector layer-algebra --help
```
If the distro GDAL is older than 3.12, add the ubuntugis PPA (the script does
this automatically):
```bash
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt update && sudo apt install gdal-bin
```

**pyarrow / pandas import fails inside QGIS, even though the script "installed"
them**
QGIS may be running a different `python3` than the one the script used. Confirm
which interpreter QGIS uses (Plugins → Python Console: `import sys; print(sys.executable)`),
then re-run with that path:
```bash
QGIS_PYTHON=/usr/bin/python3.12 bash ./install-emds-runtime-deps.sh
```
On Ubuntu 24.04+ pip refuses to touch the system Python without
`--break-system-packages` (PEP 668); the script adds that flag automatically.

**Snap or Flatpak QGIS**
Those run in a confined sandbox with their own bundled Python and restricted
filesystem access, so this script (and often the external `gdal` CLI) won't
reach them. Use the **qgis.org apt** build instead.

**"Could not locate engine_bridge.py"** at plugin load
The plugin was installed from an un-staged copy (the raw source folder rather
than the packaged ZIP). Reinstall the official plugin ZIP via *Install from ZIP*.

**No apt / no sudo**
The script skips apt and tries pip for the Python packages. Install GDAL 3.12+
and `libicu` yourself (conda, source build, or a package manager you have), then
re-run to handle the Python packages and engine chmod.

---

Building/packaging the plugin itself is documented in
`docs/deployment-builds.md`.
