bitchat/localPackages/Tor/BITCHAT_TOR.md

**BitChat Tor Build Notes**

- Date: See repo history for the commit you pulled
- Output: `tor-nolzma.xcframework` (static, C-only)
- Platforms: iOS device (arm64), iOS simulator (arm64), macOS (arm64)
- Goal: Minimize binary size while retaining client functionality

**Overview**
- We built a minimal Tor static xcframework with LZMA disabled to reduce size and complexity.
- The artifact contains only the C libraries (Tor + libevent + OpenSSL) and their headers. Objective‑C wrappers (`TORThread`, `TORController`, etc.) are not compiled into this minimal artifact to keep size down.
- This xcframework is suitable for iOS and macOS targets that link the Objective‑C wrappers as source (or use CocoaPods to bring them in).

**Component Versions**
- Tor: 0.4.8.17
- libevent: 2.1.12
- OpenSSL: 3.5.1
- liblzma: not linked (intentionally disabled)

**Build Environment**
- Xcode with iOS and macOS SDKs
- Homebrew tools: `autoconf`, `automake`, `libtool`, `gettext`
- Install prerequisites from repo root: `brew bundle`

**Command Used**
- Minimal build (nolzma), with persistent logs: `./build-xcframework.sh -md`
  - `-m` = minimal mode
  - `-d` = keep build dir and logs under `build/`

**What Minimal Mode Does**
- Targets: `iphoneos/arm64`, `iphonesimulator/arm64`, `macosx/arm64`.
- Disables LZMA in Tor (`--enable-lzma=no`) and removes zstd.
- Trims OpenSSL features: `no-zlib no-comp no-ssl3 no-tls1 no-tls1_1 no-dtls no-srp no-psk no-weak-ssl-ciphers no-engine no-ocsp`.
- Compiles with size-first flags: `-Os -ffunction-sections -fdata-sections`; bitcode is not embedded.
- Statically links Tor, libevent, and OpenSSL into a single library per slice inside the framework.
- Copies public headers from Tor/libevent/OpenSSL into the framework `Headers` directory.

**Resulting Slices (approx sizes)**
- Folder size: ~73 MB (`tor-nolzma.xcframework`)
- Binaries (non-fat, measured on this build):
  - iOS arm64 (device): ~16.49 MB
  - iOS arm64 (simulator): ~15.32 MB
  - macOS arm64: ~15.60 MB

Note: Sizes vary slightly by Xcode/SDK versions and environment.

**Integrating in BitChat**
- Add `tor-nolzma.xcframework` to your app target(s). Xcode will select the correct slice for device/simulator/macOS.
- Link `libz.tbd` (Tor depends on zlib).
- Keep app link-time stripping enabled for best results:
  - Other Linker Flags: add `-dead_strip`
  - Avoid `-ObjC` if possible (prevents dead stripping)
  - Consider enabling ThinLTO/LTO in the app for further size gains
- Objective‑C API (wrappers):
  - Not included in this minimal xcframework. Use one of:
    - CocoaPods: `Tor/CTor-NoLZMA` subspec (brings `TORThread`, `TORController` sources + links the xcframework), or
    - Vendor the ObjC sources from `Tor/Classes/CTor` and `Tor/Classes/Core` directly into your project.

**Rebuilding**
- Ensure prerequisites: `brew bundle`
- Minimal nolzma, iOS+sim+macOS: `./build-xcframework.sh -m`
- Logs (if `-d`): `build/*.log` and per-component logs like `build/libtor-nolzma-<sdk>-<arch>.log`

**LZMA Trade‑off (for reference)**
- We measured that enabling LZMA adds roughly ~0.25 MB per slice to the binary on this setup. For a 3‑slice xcframework, expect ~0.7–0.8 MB more overall.
- If you want the LZMA variant with the same minimal trimming: `./build-xcframework.sh -Md` (outputs `tor.xcframework`).

**Key Flags (for auditing)**
- OpenSSL `./Configure` adds: `no-shared` and, in minimal modes, `no-zlib no-comp no-ssl3 no-tls1 no-tls1_1 no-dtls no-srp no-psk no-weak-ssl-ciphers no-engine no-ocsp`
- libevent `./configure`: `--disable-openssl --disable-samples --disable-regress --enable-static --disable-shared`
- Tor `./configure` (highlights):
  - `--enable-pic --disable-module-relay --disable-module-dirauth --disable-unittests`
  - `--enable-static-openssl --enable-static-libevent`
  - `--disable-asciidoc --disable-manpage --disable-html-manual --disable-zstd`
  - `--enable-lzma=no` (in this build)
- Compiler flags: `-Os -ffunction-sections -fdata-sections`; no bitcode
- Minimum OS: iOS 12.0, macOS 10.13

**Verification Tips**
- Check slices: `lipo -info tor-nolzma.xcframework/*/tor-nolzma.framework/tor-nolzma`
- Ensure headers present: `ls tor-nolzma.xcframework/*/tor-nolzma.framework/Headers`
- Link test: build a small app and add `-dead_strip`; confirm successful run and circuit establishment via control port.

**Notes**
- This minimal build avoids bundling large GeoIP resources. If you need GeoIP, embed the GeoIP bundle (or use the `Tor/GeoIP-NoLZMA` subspec) and set `TORConfiguration.geoipFile`/`geoip6File`.
- Static linking maximizes the app’s ability to dead‑strip unused code across the boundary.