Skip to main content

Machine Migration Checklist

This page records the path-sensitive and machine-sensitive checks required to move Android and iOS development or release work to another machine.

Files and settings to verify​

local.properties​

Android Studio or Gradle usually regenerates this file per machine. The important value is:

sdk.dir=/absolute/path/to/Android/sdk

Check these locations:

  • apps/mobile/android/local.properties
  • apps/pos-terminal/android/local.properties

Do not commit machine-specific SDK paths unless the team intentionally wants them tracked.

Shell environment​

Verify these environment variables when Gradle cannot find Java or the Android SDK:

  • JAVA_HOME
  • ANDROID_HOME
  • ANDROID_SDK_ROOT

Hardcoded path assumptions​

Repository scripts should prefer relative paths. The current apps/mobile/package.json APK install script is relative and should be safe to move across machines.

Still check machine-local path assumptions in:

  • shell aliases
  • CI/CD scripts
  • Android Studio local settings
  • untracked helper scripts on a developer machine

Migration steps​

  1. Clone the repo to the new machine.
  2. Install Node, Yarn, Java, Android SDK, the required NDK, Xcode, CocoaPods, and CMake.
  3. Run yarn install from the monorepo root.
  4. Open Android Studio once so SDK components and local.properties can be created or refreshed.
  5. Verify JAVA_HOME, ANDROID_HOME, and ANDROID_SDK_ROOT.
  6. Verify release keystore location and signing properties.
  7. Run yarn mobile:android for a dev build.
  8. Run yarn mobile:apk or yarn mobile:aab for release packaging.

iOS setup checks​

For mobile iOS work, start from:

cd apps/mobile/ios
pod install

Before running pod install or xcodebuild on a new machine, verify:

  • Xcode has completed first launch and required components are installed.
  • Simulator runtime is installed from Xcode Settings.
  • cmake --version works.
  • The machine can reach GitHub, because some pods are downloaded from GitHub.
  • yarn install was run at the repo root so root postinstall patches are applied.

If xcodebuild reports first-launch or missing plugin issues, run:

xcodebuild -runFirstLaunch

The mobile iOS Podfile contains repo-specific recovery fixes:

  • It recreates gRPC-Core.modulemap symlinks under Pods/Headers/Private/grpc and Pods/Headers/Public/grpc.
  • It removes -weak_framework "FirebaseFirestoreInternal" from generated app xcconfigs to avoid link failures.

The root postinstall script runs scripts/patch-react-native-view-shot-ios.js, which patches react-native-view-shot for React Native new architecture by using RCTScrollViewComponentView when required.

Simulator smoke test:

cd apps/mobile/ios
xcodebuild -workspace BsrPosPlus.xcworkspace -scheme BsrPosPlus -configuration Debug -sdk iphonesimulator CODE_SIGNING_ALLOWED=NO build

Known repo-specific notes​

  • Mobile release packaging is already wired through workspace scripts at the repo root.
  • Terminal app currently has android and ios run scripts, but no root-level terminal:apk or terminal:aab scripts yet.
  • apps/pos-terminal/android/app/build.gradle has additional afterEvaluate dependencies for react-native-worklets and react-native-reanimated, so CMake or prefab issues on a new machine are likely to show up there first.
  • apps/mobile/android/app/google-services.json and apps/pos-terminal/android/app/google-services.json exist in the repo, so Firebase config is not purely machine-local.
  • apps/mobile/ios/Podfile includes iOS pod recovery hooks for gRPC and FirebaseFirestoreInternal link issues.
  • Root package.json has a postinstall script that patches react-native-view-shot after dependency install.

First checks when a build fails​

  1. JAVA_HOME points to a real JDK.
  2. sdk.dir points to the installed Android SDK.
  3. The required SDK platform, build-tools, and NDK are installed.
  4. The release keystore path exists and signing secrets are loaded.
  5. Any absolute path in machine-local scripts or aliases still matches the new machine.
  6. For iOS, Xcode first launch is complete, simulator runtime is installed, CMake exists, GitHub is reachable, pod install has completed, and root yarn install has run the postinstall patch.