diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e64f7cff..15a38be7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,18 +62,69 @@ exact Flutter version declared in `.fvmrc` and replace `fvm flutter` with fvm flutter run --dart-define="GIT_COMMIT=$(git rev-parse --short=8 HEAD)" ``` -For iOS, run `bash scripts/build_ios.sh` on macOS, then `(cd ios && pod install)` -before opening `ios/Runner.xcworkspace`. The application uses the Rust backend. - The About footer shows the short commit supplied through `GIT_COMMIT` at compile time. The Android build script and iOS release workflow supply it automatically. Include the same `--dart-define` when running Flutter build commands directly; without it, the footer shows only the copyright. -Android release builds also require the pinned Discord Social SDK. See -[Discord build setup](DISCORD.md) for local staging and the CI decryption secret. -`bash scripts/build_android.sh` verifies that every release APK contains the -native integration; debug builds can run without the SDK. +## Building the App + +### Android APKs + +For production releases, stage the official Discord Social SDK with +`bash scripts/setup_discord_sdk.sh /path/to/discord_social_sdk`, then build: + +```bash +bash scripts/build_android.sh --production +``` + +Production mode requires the staged SDK and rejects `--lite`. Release CI uses +this mode and requires Discord on both Android and iOS. Fresh hosted runners +must prepare the SDK before the release checks can pass. See +[Discord build setup](third_party/spotiflac_discord/README.md#build-setup) for +local staging and the CI decryption secret. Unencrypted SDK files are not +committed to the repository. + +For development release APKs, use `bash scripts/build_android.sh`. Full builds +remain the default; add `--lite` to omit the optional Discord SDK while keeping +playback and downloads. Debug builds can also run without the SDK. + +To build only ARM64, set `SPOTIFLAC_RUST_ANDROID_ABIS=arm64-v8a`. The script uses +the Flutter version in `.fvmrc` and audits the selected split APKs and universal +APK. Android Gradle builds the Rust native artifacts automatically. + +### iOS Builds + +On macOS, run `bash scripts/build_ios.sh`, then `(cd ios && pod install)` before +opening `ios/Runner.xcworkspace`. The application uses the Rust backend. + +For iOS Lite, run CocoaPods and the app build with `SPOTIFLAC_DISCORD_SDK=0`. +An existing Pods installation must be regenerated with that setting. Production +release CI requires the staged Discord SDK on iOS as well. + +For native iOS codec checks, see the +[FFmpeg capability probe](scripts/README_ios_ffmpeg_capabilities.md). + +### Android Crash Symbols + +Android release builds, including plain `flutter build apk --release`, keep Dart +debug data in `build/symbols/android/app..symbols` to reduce APK +size. The release script also uses `--obfuscate` to shorten internal Dart names; +when building directly, add `--obfuscate --split-debug-info=build/symbols/android` +for the smaller APK. An explicit `--split-debug-info` path overrides the default; +plain `--analyze-size` builds retain Flutter's normal behavior. + +Keep these symbols with the matching APK before another local build replaces +them. Decode a trace with: + +```bash +fvm flutter symbolize --debug-info= --input=crash.txt +``` + +CI and release jobs retain an `android-symbols-…` artifact with the commit, APK +SHA-256 hashes, Dart symbols, and R8 mapping, identified by run and attempt. +Archive it before its 90-day retention expires and match the reported APK hash +when choosing symbols; equal version numbers do not guarantee a match. ## Project Boundaries diff --git a/README.md b/README.md index b401125d..66f8e659 100644 --- a/README.md +++ b/README.md @@ -59,44 +59,10 @@ Extensions let the community add new music sources and features without waiting ## Development SpotiFLAC Mobile combines a Flutter/Dart UI, a Rust backend from -[`rust_backend/`](rust_backend/), and thin Android/iOS platform bridges. Android -Gradle builds the Rust native artifacts automatically. Tool versions are pinned in -[`rust_backend/rust-toolchain.toml`](rust_backend/rust-toolchain.toml) and -[`rust_backend/Cargo.lock`](rust_backend/Cargo.lock). +[`rust_backend/`](rust_backend/), and thin Android/iOS platform bridges. -Start with the [Contributing Guide](CONTRIBUTING.md) for the development setup, -project boundaries, validation commands, and pull request checklist. - -Build production APKs with `bash scripts/build_android.sh --production`; -this requires the staged Discord SDK and rejects Lite. CI releases use this -mode and require Discord on both Android and iOS. Stage the official SDK with -`scripts/setup_discord_sdk.sh` in the build environment before releasing; -the SDK is not committed to the repository. A fresh hosted runner must be -provided with the SDK before these release checks can pass. - -For development release APKs, use `bash scripts/build_android.sh`; use `--lite` to omit -the optional Discord SDK while keeping playback and downloads. Full builds -remain the default. To build only ARM64, set -`SPOTIFLAC_RUST_ANDROID_ABIS=arm64-v8a`. The script uses the Flutter version in -`.fvmrc` and audits the selected split APKs and universal APK. For iOS Lite, -run CocoaPods and the app build with `SPOTIFLAC_DISCORD_SDK=0`; an existing Pods -installation must be regenerated with that setting. - -Android release builds, including plain `flutter build apk --release`, keep Dart -debug data in `build/symbols/android/app..symbols` to reduce APK -size. The release script also uses `--obfuscate` to shorten internal Dart names; -when building directly, add `--obfuscate --split-debug-info=build/symbols/android` -for the smaller APK. An explicit `--split-debug-info` path overrides the default; -plain `--analyze-size` builds retain Flutter's normal behavior. Keep these symbols -with the matching APK before another local build replaces them. Decode a trace -with `flutter symbolize --debug-info= --input=crash.txt`. - -CI and release jobs retain an `android-symbols-…` artifact with the commit, APK -SHA-256 hashes, Dart symbols, and R8 mapping, identified by run and attempt. -Archive it before its 90-day retention expires and match the reported APK hash -when choosing symbols; equal version numbers do not guarantee a match. - -For native iOS codec checks, see the [FFmpeg capability probe](scripts/README_ios_ffmpeg_capabilities.md). +See the [Contributing Guide](CONTRIBUTING.md) for setup, Android and iOS builds, +Full/Lite variants, crash symbols, validation, and pull request guidelines. ---