Update build docs: DMG usage, arm64 cross-compile, embedded mode

frstrtr · frstrtr · commit a3ff656bbb70 · 2026-04-13T15:24:41.000+04:00
macOS: add DMG installation instructions, SHA256 verification, arm64
cross-compile guide (secp256k1 from source), DMG packaging, cmake
PATH fix for SSH sessions.

Linux: update running section for embedded SPV mode (no daemon needed),
fix default ports table, add data directory section.

Windows: add --embedded-ltc/--embedded-doge flags, SHA256 verification,
running from build instructions.
diff --git a/doc/build-macos.md b/doc/build-macos.md
@@ -18,21 +18,46 @@ This guide covers building c2pool from source on macOS.
 > major versions are the most common source of build failures on untested
 > configurations.
 
-## Option 1: Pre-built binary
+## Option 1: Pre-built DMG (recommended)
 
 Download from the [Releases page](https://github.com/frstrtr/c2pool/releases):
-- **Intel Mac**: `c2pool-VERSION-macos-x86_64.zip`
-- **Apple Silicon (M1/M2/M3/M4)**: `c2pool-VERSION-macos-arm64.zip`
+- **Intel Mac**: `c2pool-VERSION-macos-x86_64.dmg`
+- **Apple Silicon (M1/M2/M3/M4)**: `c2pool-VERSION-macos-arm64.dmg`
 
 ```bash
-unzip c2pool-*-macos-*.zip
-cd c2pool-*-macos-*
+# Mount the DMG
+hdiutil attach c2pool-*-macos-*.dmg
+
+# Copy to your preferred location
+cp -R /Volumes/c2pool-*/  ~/c2pool
+
+# Unmount
+hdiutil detach /Volumes/c2pool-*
+
+# Run
+cd ~/c2pool
 ./start.sh
 ```
 
 Dashboard: `http://localhost:8080` — Stratum: `stratum+tcp://YOUR_IP:9327`
 
-> **macOS Gatekeeper**: On first run, macOS may block the binary. Open System Settings > Privacy & Security and click "Allow Anyway", or run: `xattr -d com.apple.quarantine c2pool`
+The DMG contains everything needed: the binary, bundled `libsecp256k1`, web dashboard,
+config templates, block explorer, and a start script. No additional dependencies required.
+
+> **macOS Gatekeeper**: On first run, macOS may block the binary. Open
+> System Settings > Privacy & Security and click "Allow Anyway", or run:
+> ```bash
+> xattr -dr com.apple.quarantine ~/c2pool
+> ```
+
+### Verifying the download
+
+Each release includes a `SHA256SUMS` file. Verify your download:
+
+```bash
+shasum -a 256 c2pool-*-macos-*.dmg
+# Compare output with the published SHA256SUMS
+```
 
 ---
 
@@ -167,23 +192,90 @@ c2pool stores its data in `~/.c2pool/`:
 
 ---
 
-## Universal binary (optional)
+## Cross-compiling for arm64 on an Intel Mac
+
+If you have an Intel Mac and want to build an arm64 binary (e.g. for distribution):
 
-To build a fat binary that runs natively on both Intel and Apple Silicon:
+### 1. Build secp256k1 for arm64
+
+Homebrew's secp256k1 is native-only. Cross-compile from source:
+
+```bash
+git clone --depth 1 --branch v0.7.1 https://github.com/bitcoin-core/secp256k1.git
+cd secp256k1
+mkdir build && cd build
+cmake .. -DCMAKE_OSX_ARCHITECTURES=arm64 \
+    -DCMAKE_INSTALL_PREFIX=$HOME/arm64-deps \
+    -DSECP256K1_BUILD_TESTS=OFF \
+    -DSECP256K1_BUILD_EXHAUSTIVE_TESTS=OFF \
+    -DSECP256K1_BUILD_BENCHMARK=OFF \
+    -DSECP256K1_BUILD_EXAMPLES=OFF
+cmake --build . -j$(sysctl -n hw.ncpu)
+cmake --install . --prefix $HOME/arm64-deps
+```
+
+### 2. Build c2pool for arm64
 
 ```bash
-cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"
+cd c2pool
+mkdir build-arm64 && cd build-arm64
+cmake .. -DCMAKE_BUILD_TYPE=Release \
+    -DCMAKE_OSX_ARCHITECTURES=arm64 \
+    -DSECP256K1_INCLUDE_DIRS=$HOME/arm64-deps/include \
+    -DSECP256K1_LIBRARIES=$HOME/arm64-deps/lib/libsecp256k1.dylib
 cmake --build . --target c2pool -j$(sysctl -n hw.ncpu)
 ```
 
-> **Note**: Universal builds require that all Homebrew dependencies are also
-> available for both architectures. This may require additional setup.
-> For most users, building natively for your Mac's architecture is simpler.
+Binary: `build-arm64/src/c2pool/c2pool` (Mach-O arm64)
+
+> **Important**: Use a persistent location for `arm64-deps` (not `/tmp/`).
+> The arm64 secp256k1 library is needed at build time and bundled into the DMG.
+
+### 3. Build the DMG
+
+```bash
+bash installer/macos/create-dmg.sh build-arm64/src/c2pool/c2pool arm64
+```
+
+---
+
+## Building a DMG package
+
+The `installer/macos/create-dmg.sh` script packages a binary with all
+required assets into a distributable `.dmg` file:
+
+```bash
+# Native architecture
+bash installer/macos/create-dmg.sh build/src/c2pool/c2pool
+
+# Specific architecture
+bash installer/macos/create-dmg.sh build/src/c2pool/c2pool x86_64
+bash installer/macos/create-dmg.sh build-arm64/src/c2pool/c2pool arm64
+```
+
+The DMG includes: binary, `libsecp256k1.6.dylib` (with `install_name_tool`
+fixup for `@executable_path`), web-static, explorer, config, start.sh, README.
 
 ---
 
 ## Troubleshooting
 
+### `cmake` not found over SSH
+
+Homebrew binaries are at `/usr/local/bin` (Intel) or `/opt/homebrew/bin` (Apple Silicon).
+Non-login SSH sessions may not load your shell profile. Prefix commands:
+
+```bash
+export PATH=/usr/local/bin:$PATH    # Intel
+export PATH=/opt/homebrew/bin:$PATH  # Apple Silicon
+```
+
+Or add to `~/.zshenv` (loaded by all zsh sessions, including non-login):
+
+```bash
+echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshenv
+```
+
 ### `brew` not found after installation
 
 Add Homebrew to your PATH:
diff --git a/doc/build-unix.md b/doc/build-unix.md
@@ -152,36 +152,37 @@ ctest --output-on-failure -j$(nproc)
 
 All examples assume you are in the repository root.
 
-### Integrated mode — full pool (LTC + DOGE merged mining)
+### Integrated mode — embedded SPV (no daemon required)
+
+The default mode uses embedded LTC and DOGE SPV nodes. No litecoind or
+dogecoind installation needed.
 
 ```bash
-./build/src/c2pool/c2pool \
-    --integrated \
-    --net litecoin \
-    --coind-address 127.0.0.1 --coind-rpc-port 9332 \
-    --coind-p2p-port 9333 \
-    --merged DOGE:98:127.0.0.1:44556:dogerpc:rpcpass \
-    --address YOUR_LTC_ADDRESS \
-    --give-author 2 \
-    litecoinrpc RPCPASSWORD
+./build/src/c2pool/c2pool --integrated --net litecoin --dashboard-dir web-static
 ```
 
-### Testnet smoke-test
+- Dashboard: `http://localhost:8080`
+- Stratum: `stratum+tcp://YOUR_IP:9327` (miners set LTC address as username)
+- P2P: port 9326 (sharechain peers)
+
+### With external coin daemon (optional)
+
+If you run a local litecoind, add it as a priority peer for faster sync:
 
 ```bash
-./build/src/c2pool/c2pool --integrated --testnet
+./build/src/c2pool/c2pool --integrated --net litecoin \
+    --dashboard-dir web-static \
+    --coind-p2p-port 9333
 ```
 
-### Sharechain-only node
+### With YAML config file
 
 ```bash
-./build/src/c2pool/c2pool \
-    --sharechain \
-    --net litecoin \
-    --coind-address 127.0.0.1 --coind-rpc-port 9332 \
-    litecoinrpc RPCPASSWORD
+./build/src/c2pool/c2pool --config config/c2pool_mainnet.yaml --dashboard-dir web-static
 ```
 
+See `config/c2pool_mainnet.yaml` for all available options with documentation.
+
 ### Full option reference
 
 ```bash
@@ -192,15 +193,33 @@ All examples assume you are in the repository root.
 
 | Port | Purpose |
 |------|--------|
-| 9338 | P2Pool sharechain peer-to-peer |
-| 9327 | Stratum mining server + HTTP API |
+| 9326 | P2Pool sharechain peer-to-peer |
+| 9327 | Stratum mining server |
+| 8080 | Web dashboard / JSON-RPC API |
+| 9333 | LTC P2P (embedded SPV) |
+| 22556 | DOGE P2P (embedded SPV) |
 
 ---
 
-## 7. Configuration file (optional)
+## 7. Data directory
+
+c2pool stores its data in `~/.c2pool/`:
+
+```
+~/.c2pool/
+  debug.log                    # Main log file (rotated at 100MB)
+  sharechain_leveldb/          # Persistent sharechain storage
+  litecoin/embedded_headers/   # LTC SPV header cache
+  dogecoin/embedded_headers/   # DOGE SPV header cache
+  litecoin/utxo_leveldb/       # LTC UTXO set
+  dogecoin/utxo_leveldb/       # DOGE UTXO set
+  crash.log                    # Crash log (if any, at /tmp/c2pool_crash.log)
+```
+
+## 8. Configuration file (optional)
 
-Pass `--config path/to/config.yaml` to load settings from YAML.  
-Templates are in `doc/configs-templates/`.
+Pass `--config path/to/config.yaml` to load settings from YAML.
+See `config/c2pool_mainnet.yaml` for all available options with documentation.
 
 ---
 
diff --git a/doc/build-windows.md b/doc/build-windows.md
@@ -20,11 +20,22 @@ installed separately.
 ### Running
 
 ```
-c2pool.exe --integrated --net litecoin --dashboard-dir web-static
+c2pool.exe --integrated --net litecoin --embedded-ltc --embedded-doge --dashboard-dir web-static
 ```
 
-Dashboard: `http://localhost:8080`
-Stratum: `stratum+tcp://YOUR_IP:9327` (miners set LTC address as username)
+No litecoind or dogecoind needed — embedded SPV nodes sync via P2P.
+
+- Dashboard: `http://localhost:8080`
+- Stratum: `stratum+tcp://YOUR_IP:9327` (miners set LTC address as username)
+
+### Verifying the download
+
+Each release includes a `SHA256SUMS` file. Verify your download:
+
+```powershell
+Get-FileHash c2pool-*-windows-*.exe -Algorithm SHA256
+# Compare output with the published SHA256SUMS
+```
 
 ---
 
@@ -94,6 +105,12 @@ Binary: `build\src\c2pool\Release\c2pool.exe`
 
 > **First build**: ~20-30 min (Boost compiles from source via Conan).
 
+### Running from build
+
+```cmd
+build\src\c2pool\Release\c2pool.exe --integrated --net litecoin --embedded-ltc --embedded-doge --dashboard-dir web-static
+```
+
 ### Building the installer
 
 Install [Inno Setup 6](https://jrsoftware.org/isdl.php), then:
