docs: add quickstart.md (English)

Step-by-step setup guide covering system prerequisites, venv creation, dependency installation (test-only and test+Qt/QML variants), running from source (Bitcoin and BitcoinPurple networks, GUI/text/daemon modes), running tests, and a project structure quick-reference table
2026-04-29 10:10:23 +02:00
parent 88525ef510
commit ea8f27358f
1 changed files with 113 additions and 0 deletions
@@ -0,0 +1,113 @@
+# Quickstart — Electrum (running from source)
+
+## System prerequisites
+
+```bash
+sudo apt-get install git python3.12 python3.12-venv libsecp256k1-dev xvfb
+```
+
+> `libsecp256k1-dev` avoids recompiling the C library locally.
+> `xvfb` is only needed to run QML tests without a physical display.
+
+---
+
+## 1. Clone the repository
+
+---
+
+## 2. Create and activate the virtual environment
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+---
+
+## 3. Install dependencies
+
+### Tests only (no GUI)
+
+```bash
+ELECTRUM_ECC_DONT_COMPILE=1 pip install -r contrib/requirements/requirements.txt \
+  "cryptography>=2.6" "dnspython[DNSSEC]>=2.2,<2.5" \
+  pytest coverage \
+  "pycryptodomex>=3.7" pyaes \
+  && ELECTRUM_ECC_DONT_COMPILE=1 pip install -e .
+```
+
+### Tests + Qt/QML GUI (Android)
+
+```bash
+ELECTRUM_ECC_DONT_COMPILE=1 pip install -r contrib/requirements/requirements.txt \
+  "cryptography>=2.6" "dnspython[DNSSEC]>=2.2,<2.5" \
+  pytest coverage \
+  "pycryptodomex>=3.7" pyaes \
+  "pyqt6~=6.10" "pyqt6-qt6~=6.10" \
+  && ELECTRUM_ECC_DONT_COMPILE=1 pip install -e .
+```
+
+---
+
+## 4. Run Electrum from source
+
+```bash
+# Qt GUI (default)
+./run_electrum
+
+# BitcoinPurple network
+./run_electrum --bitcoinpurple
+
+# BitcoinPurple testnet
+./run_electrum --bitcoinpurple_testnet
+
+# QML GUI (Android-style)
+./run_electrum --gui qml
+
+# Text UI (terminal)
+./run_electrum --gui text
+
+# Daemon mode
+./run_electrum daemon -d
+```
+
+---
+
+## 5. Run tests
+
+```bash
+# All tests
+pytest tests -v
+
+# Parallel (requires pytest-xdist)
+pytest tests -v -n auto
+
+# Single file
+pytest tests/test_bitcoin.py -v
+
+# BitcoinPurple tests
+pytest tests/test_bitcoinpurple.py -v
+
+# blockchain + bitcoin + BitcoinPurple together
+pytest tests/test_blockchain.py tests/test_bitcoin.py tests/test_bitcoinpurple.py -v
+
+# QML tests (requires PyQt6 and xvfb)
+xvfb-run pytest tests/qml/ -v
+```
+
+---
+
+## Project structure (quick reference)
+
+| Path | Contents |
+|---|---|
+| `run_electrum` | Main entry point |
+| `electrum/constants.py` | Network parameters (Bitcoin, BitcoinPurple, …) |
+| `electrum/blockchain.py` | Header verification and PoW difficulty |
+| `electrum/wallet.py` | Wallet logic |
+| `electrum/lnworker.py` | Lightning Network |
+| `electrum/gui/qt/` | Desktop Qt GUI |
+| `electrum/gui/qml/` | Mobile QML GUI (Android) |
+| `electrum/chains/bitcoinpurple/` | BitcoinPurple servers and checkpoints |
+| `tests/test_bitcoinpurple.py` | BitcoinPurple test suite |
+| `contrib/requirements/` | Dependency files |