# Developer Setup

How to go from a fresh checkout to a running desktop app.

## TL;DR

```bash
git clone https://github.com/lt-uhura/bitcoinarmory
cd bitcoinarmory
scripts/install-deps.sh      # one-shot bootstrap (idempotent)
cd tauri && cargo tauri dev  # build + run the desktop app
```

`scripts/install-deps.sh` is the single entrypoint. Re-running it only installs
what's missing.

## What the bootstrap installs

This is a **hybrid Rust + Tauri + Python** project, so a `requirements.txt` alone
can't capture everything — `install-deps.sh` handles the rest:

| Dependency | Why it's needed | How it's installed |
|---|---|---|
| **Rust toolchain** (`rustc`, `cargo`) | Compiles the Tauri desktop shell | `rustup` |
| **Tauri CLI** (`cargo-tauri`) | Provides the `cargo tauri` command | `cargo binstall` / `cargo install` |
| **libsecp256k1** | Fast EC math for online Silent Payment scanning | `brew` / `apt` / `dnf` |
| **python3 ≥ 3.10** | Runs the wallet logic as a sidecar | must be pre-installed |
| **Python packages** | `cbor2` (QR/UR transport) + `cryptography` (wallet encryption) | `pip install -r requirements.txt` |

### Required vs. recommended

- **Required** to build and run `cargo tauri dev`: Rust, Tauri CLI, `python3 ≥ 3.10`.
- **Recommended** (the app still runs without them, via slower fallbacks):
  - `libsecp256k1` — without it, online SP scanning uses pure-Python ECDH and pins a CPU core.
  - `cryptography` — without it, wallet encryption falls back to system libcrypto, then a slow pure-Python AES-GCM.

## How Python is wired (important for dev)

In a **dev build** (`cargo tauri dev`), the Rust shell invokes the **bare `python3`
on your `PATH`** with `PYTHONPATH` set to the repo root
(`tauri/src-tauri/src/python.rs`). It does **not** use the bundled Python runtime —
that's only assembled for release builds.

Consequences:

- The packages in `requirements.txt` must be installed into the **same `python3`**
  you'll have active when you run `cargo tauri dev`.
- If you prefer a virtualenv, activate it **before** running both the bootstrap and dev:
  ```bash
  python3 -m venv .venv && source .venv/bin/activate
  scripts/install-deps.sh
  cd tauri && cargo tauri dev   # keep the venv active
  ```
  (Some system Pythons are PEP 668 "externally managed" and reject a global
  `pip install`; a venv is the clean fix. The bootstrap will fall back to
  `pip install --user` and print this guidance if needed.)

## The `python-bundle/` directory

`tauri/src-tauri/python-bundle/` is a **generated** directory (gitignored) that
Tauri lists as a bundled resource, so the build fails if it's missing. It's
produced by `scripts/prepare-resources.py`, wired into `tauri.conf.json` as both
`beforeBuildCommand` and `beforeDevCommand` — so `cargo tauri dev` regenerates it
automatically. (In dev the sidecar actually runs from the repo source via the
system `python3`; the bundle just has to exist to satisfy Tauri's resource glob.)
If you ever see `glob pattern python-bundle/**/* ... didn't match any files`, run
`python3 scripts/prepare-resources.py` once to recreate it.

## iOS note

The iOS app (`ios/`) does **not** use `requirements.txt` or the system Python. It
vendors pure-Python source from `packages/` (e.g. `packages/cbor2`) via
`scripts/bundle-python-source.sh` and falls back to libcrypto / pure Python for
encryption. This is why `cryptography` is a desktop-only dependency and `cbor2` is
pinned `<6` (the 6.x native extension can't ship in the iOS source bundle).

## Release builds

For a packaged `.app` / `.dmg`, use `scripts/build-macos.sh`. That path downloads a
standalone Python runtime and `pip install`s `cryptography` into it — separate from
your dev Python. See the script and `.github/workflows/build-release.yml` for the
full release pipeline (code signing, notarization, DMG creation).
