# EMDS Workbench – macOS Dependency Installer

This folder contains everything needed to prepare your Mac so the **EMDS Study Area** and overlay tools work correctly inside QGIS.

## Why this is needed

The EMDS plugin uses:
- A modern **GDAL** command-line tool (≥ 3.12) for vector layer algebra operations
- The **pyarrow** Python package inside QGIS’s own Python environment

A standard QGIS installation on macOS does not include these, so the plugin will fail to load or run certain tools until you run this installer once.

## Recommended method (easiest for most users)

### 1. Use the `.command` file (recommended)

1. Double-click `install-emds-runtime-deps.command`.
2. If macOS opens it in a text editor instead of running it:
   - Open **Terminal**
   - Drag the `install-emds-runtime-deps.command` file into the Terminal window
   - Press **Return** (this runs the `chmod +x` command automatically)
3. A Terminal window will open and show progress with `==>` messages.
4. Answer any prompts (or it can run mostly automatically).
5. When it says **“All required EMDS macOS runtime dependencies are available”**, close the Terminal window.
6. **Completely quit and restart QGIS**.

That’s it. You only need to do this once (or after major QGIS / macOS updates).

## Alternative: Nicer double-click experience (no chmod ever)

If you prefer a real application icon and zero Terminal setup steps:

1. Open the file `Install EMDS Dependencies.applescript` in **Script Editor** (Applications → Utilities → Script Editor).
2. Click **File → Save As…**
   - Name: `Install EMDS Dependencies`
   - File Format: **Application**
3. (Optional but nice) Put the saved `.app` in your Applications folder or Dock.
4. Double-click the new app. It will show a friendly dialog and then open Terminal with progress.

**Note on downloaded apps**: macOS may show a security warning the first time. Right-click the app → **Open**, or run this command in Terminal:

```zsh
xattr -cr "~/Downloads/Install EMDS Dependencies.app"
```

## After installation

- **Restart QGIS completely** (quit → reopen).
- The EMDS Study Area tools and overlays should now work.
- You can delete this installer folder afterward if you wish.

## Troubleshooting

| Problem                              | Solution |
|--------------------------------------|----------|
| Opens in TextEdit / code editor      | Use the `chmod` step above or use the AppleScript `.app` method |
| "Operation not permitted" or permission errors | Run the installer from an admin account or use the AppleScript version (it can request privileges) |
| Homebrew / GDAL takes a long time    | Normal on first run (especially on Apple Silicon). Just let it finish. |
| Still fails after restart            | Re-run the installer, then restart QGIS again. Check the Terminal output for errors. |
| Multiple QGIS versions installed     | The installer usually picks the newest. You can force one with environment variables if needed. |

## Advanced / manual run

You can also run it directly from Terminal:

```zsh
cd /path/to/this/folder
chmod +x install-emds-runtime-deps.command
./install-emds-runtime-deps.command
```

Or with auto-accept:

```zsh
ASSUME_YES=1 ./install-emds-runtime-deps.command
```

## Support

If you run into problems, please open an issue on the EMDS GitHub repository or contact your plugin maintainer with the full Terminal output.

Thank you for using EMDS Workbench!
