From f44bd8294907c56becbe865c2948635b1d843500 Mon Sep 17 00:00:00 2001 From: Karin Berg Date: Mon, 2 Dec 2024 09:11:46 +0100 Subject: [PATCH] Add documentation about need tools and versions to build our app (#963) - Add documentation about need tools and versions to build our app - Add a example launch.json file - Add optional support for version manager 'asdf' - Add a clean_build.sh script to execute fast a clean build --- recipients_app/.tool-versions | 1 + recipients_app/.vscode/launch.json.example | 56 ++++++++ recipients_app/README.md | 129 ++++++++++++++++-- recipients_app/clean_build.sh | 34 +++++ .../docu/app_release_guides/releasing.md | 8 ++ 5 files changed, 215 insertions(+), 13 deletions(-) create mode 100644 recipients_app/.tool-versions create mode 100644 recipients_app/.vscode/launch.json.example create mode 100755 recipients_app/clean_build.sh diff --git a/recipients_app/.tool-versions b/recipients_app/.tool-versions new file mode 100644 index 000000000..f6e159696 --- /dev/null +++ b/recipients_app/.tool-versions @@ -0,0 +1 @@ +flutter 3.19.6 diff --git a/recipients_app/.vscode/launch.json.example b/recipients_app/.vscode/launch.json.example new file mode 100644 index 000000000..c641439f4 --- /dev/null +++ b/recipients_app/.vscode/launch.json.example @@ -0,0 +1,56 @@ +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + + // This is our example launch config. Set the prefered flavor, SURVEY_BASE_URL and SENTRY_URL + "version": "0.2.0", + "configurations": [ + { + "name": "stage_recipients_app (debug mode)", + "request": "launch", + "type": "dart", + "flutterMode": "debug", + "program": "lib/main.dart", + "args": [ + "--flavor", + "stage", + "--dart-define", + "SURVEY_BASE_URL=staging.socialincome.org", + "--dart-define", + "SENTRY_URL=FILL IN SENTRY URL", + + ], + }, + { + "name": "stage_recipients_app (profile mode)", + "request": "launch", + "type": "dart", + "flutterMode": "profile", + "program": "lib/main.dart", + "args": [ + "--flavor", + "stage", + "--dart-define", + "SURVEY_BASE_URL=staging.socialincome.org", + "--dart-define", + "SENTRY_URL=FILL IN SENTRY URL", + ], + }, + { + "name": "stage_recipients_app (release mode)", + "request": "launch", + "type": "dart", + "flutterMode": "release", + "program": "lib/main.dart", + "args": [ + "--flavor", + "stage", + "--dart-define", + "SURVEY_BASE_URL=staging.socialincome.org", + "--dart-define", + "SENTRY_URL=FILL IN SENTRY URL", + ], + } + ] +} diff --git a/recipients_app/README.md b/recipients_app/README.md index bf0673022..78ae1f0f2 100644 --- a/recipients_app/README.md +++ b/recipients_app/README.md @@ -2,24 +2,109 @@ Mobile App for Recipients of a Social Income. -## Basic Setup - -For the basic setup, please refer to the main [README](../README.md) - -## Getting Started - -Open `recipients_app` project folder in your development environment of -choice. Building flavor should work seamlessly for Android Studio and VS -Code with predefined build configs. +## Tools needed for building the app on an Apple Silicon Mac + +- [Homebrew](https://brew.sh/de/) +- Flutter 3.19.6, Dart 3.3.4 +- Java JDK 17 +- Android Studio LadyBug or later +- Latest vsCode +- Xcode 16.1 + +## Configure the Apple Silicon Mac environment to build our app + +- Install [Homebrew](https://brew.sh/de/) + ```shell + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + ``` +- Install Android Studio + - Set ANDROID_HOME and deprecated ANDROID_SDK_ROOT. Add the following + lines in your USER's HOME directory in your .zshrc file: + ```shell + export ANDROID_HOME="YOUR PATH TO YOUR ANDROID SDK" + export ANDROID_SDK_ROOT="$ANDROID_HOME" # ANDROID_SDK_ROOT is deprecated, but still in use + export PATH="$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools" + ``` + - Restart your terminal so that these changes take effect +- Install Java 17 via Homebrew `brew install openjdk@17` + - Homebrew is telling you to execute a symlink command, so that the + system Java wrappers can find this JDK. Please do this. + - Additionally in your USER's HOME directory in the file '.zshrc', add + the lines to set the JAVA_HOME environment variable to Java 17 and + add Java to the PATH environment variable + ```shell + export JAVA_HOME=$(/usr/libexec/java_home -v17) + export PATH="$PATH:$JAVA_HOME/bin" + ``` + - Restart your terminal so that these changes take effect +- Install Flutter + - Tell Flutter to use our Java 17 JDK and not the one bundle with + Android Studio via `flutter config --jdk-dir $JAVA_HOME`. Otherwise, + you will get the error "Unsupported class file major version 65” + when building the app for Android. + - Restart your terminal and IDE so that these changes take effect +- Install vsCode + - Install Flutter extension +- Install Xcode + - Set is as default via `sudo xcode-select -s Xcode.app` + - To agree to the Xcode license from the command line, you can use the + following command: `sudo xcodebuild -license accept` + +## Optionally: Use the version manager [asdf](https://asdf-vm.com/) + +- Install [asdf](https://asdf-vm.com/) via Homebrew with + `brew install asdf` +- Install flutter plugin for asdf via `asdf plugin-add flutter` +- Add the following lines in your .zshrc file: + ```shell + export FLUTTER_ROOT="$(asdf where flutter)" + ### asdf stuff ############ + source $(brew --prefix asdf)/libexec/asdf.sh + export ASDF_NODEJS_LEGACY_FILE_DYNAMIC_STRATEGY=latest_available + # This is optional. It installs tools defined in .tool-versions on terminal start + asdf install + ########################### + ``` + +## Build and run the app the first time with vsCode + +- Checkout main branch: + `git clone https://github.com/socialincome-san/public.git ./social-income/` +- Copy file `./.vscode/launch.json.example` and rename it to + `./.vscode/launch.json` + - Replace the value "FILL IN SENTRY URL" after "SENTRY_URL=" with the + real Sentry url to be able to use Sentry. If you do not prive a + Sentry Url, no issues will be reported to Sentry but you can still + run the app. To get the real Sentry url see + [here](https://social-income.sentry.io/settings/projects/si-mobileapp/keys/) + under "DSN". + - Decide which flavor and backend environment you want to use and + change it if necessary. +- Open `recipients_app` project folder in vsCode +- Open a terminal inside of vsCode and check `flutter --version` is + listing the right flutter version (See above or pubspec.yaml). +- Add executable permissions to the script clean_build.sh via + `chmod +x clean_build.sh` +- Run `./clean_build.sh` +- Choose in vsCode the device to deploy on (iOS Simulator, Android + emulator, real Android or iOS device) +- Run the launch configuration "stage_recipients_app (debug mode)" to + deploy and run the app on the selected devive in debug mode +- Happy testing!! + +## Available app flavors + +Building flavor should work seamlessly for Android Studio and VS Code +with predefined build configs. We have three build flavors: - `dev` -> Connecting with Firebase Emulators (Firestore and Auth) - `stage` -> Connecting with staging online firebase project - `prod` -> Connecting with production online firebase project and need - real Firebase configuration json / plist file + real Firebase configuration json / plist file (not in the repo) -For development use `dev` flavor. +For development, use the `dev` or `stage` flavor. As Firebase emulators work on your local host machine the easiest way to run app is on the Android emulator. Real devices need some additional @@ -30,7 +115,9 @@ setup. 1. Github for issue related discussion 2. Everything else on [Slack](https://social-income.slack.com/home) -## Rebuilding JSON Serialization +## How tos + +### Rebuilding JSON Serialization ``` dart run build_runner watch --delete-conflicting-outputs @@ -42,7 +129,7 @@ or dart run build_runner build --delete-conflicting-outputs ``` -## Rebuilding Translations +### Rebuilding Translations Translations are stored in lib/l10n/app_en.arb. To rebuild the translations after you changed something run: @@ -55,6 +142,22 @@ To use a translated string in the code use: `AppLocalizations.of(context).helloWorld` and import: `import 'package:flutter_gen/gen_l10n/app_localizations.dart';` +### Upgrade flutter version + +If you upgrade the flutter version, you have to change the following +locations as well: + +- pubspec.yaml + - Under 'environment' adjust the 'sdk' and 'flutter' versions +- .tool-versions (version file for version manager ASDF) + - If you use 'asdf' run the comman `asdf local flutter x.y.z` #Replace + x.y.z with the new Flutter version. + - Otherwise just update the version number in the file +- Adjust variable 'REQUIRED_VERSION' in 'clean_build.sh' +- README.md + - Find all places in the README.md which mentions the Flutter version + number + ## Testing ### Manually diff --git a/recipients_app/clean_build.sh b/recipients_app/clean_build.sh new file mode 100755 index 000000000..6afeee605 --- /dev/null +++ b/recipients_app/clean_build.sh @@ -0,0 +1,34 @@ +#!/bin/zsh + +# Exit on error +set -e + +# Check if Flutter is installed +echo "Verify Flutter is installed..." +if ! command -v flutter &> /dev/null; then + echo "Error: Flutter is not installed" + exit 1 +fi + +# Verify Flutter version +echo "Verify Flutter version..." +REQUIRED_VERSION="3.19.6" +CURRENT_VERSION=$(flutter --version | head -n 1 | awk '{print $2}') +if [ "$CURRENT_VERSION" != "$REQUIRED_VERSION" ]; then + echo "Error: Flutter version $REQUIRED_VERSION is required (current: $CURRENT_VERSION)" + exit 1 +fi + +echo "Cleaning Flutter build..." +flutter clean + +echo "Getting dependencies..." +flutter pub get + +echo "Running build runner..." +dart run build_runner build --delete-conflicting-outputs + +echo "Generating localizations..." +flutter gen-l10n + +echo "Build completed successfully!" \ No newline at end of file diff --git a/recipients_app/docu/app_release_guides/releasing.md b/recipients_app/docu/app_release_guides/releasing.md index b1d9ee46a..d710bfbba 100644 --- a/recipients_app/docu/app_release_guides/releasing.md +++ b/recipients_app/docu/app_release_guides/releasing.md @@ -1,6 +1,14 @@ # How to release the apps 1. Increment app version and build number in pubspec.yaml + + - Open 'pubspec.yaml' and increase 'version' with the desired app + version and the version code by incrementing the '+' part by 1. + Incrementing the version code is a must-have for a new prod + version. Otherwise, the stores will not accept the new app. + + Example: Current: version: 1.1.0+12 New: version: 1.1.1+13 + 1. Run CodeMagic Build "iOS Staging (Firebase App Distribution)" 1. Run CodeMagic Build "Android Staging (Firebase App Distribution)" 1. Test the app on the Staging environment. See