Skip to content

Commit a8ab370

Browse files
olerassolerass
authored
docs(readme): restructure setup by target platform and fix Android setup gaps (#7138)
The README setup instructions are organized by host OS (macOS vs Linux), which conflates host platform with target platform. macOS developers need Android setup too, but it's only documented under the Linux section (and even there it just links to the RN docs). The Developing section has the same problem: "MacOS" only mentions iOS, "Linux" only mentions Android. Furthermore, the Android setup is not easy to get working, even with the RN docs. This change restructures both sections by target platform (iOS / Android) and fills in the Android setup with the specific steps I discovered actually matter when setting up from scratch: * install JDK 17 separately (Android Studio bundles 21 which causes Kotlin/Java target mismatches) * set the Gradle JDK in Android Studio settings * bump the IDE heap for this project's size * run an initial `assembleDebug` to generate native headers before Gradle sync will succeed * always launch Android Studio from the terminal so it inherits the nvm-managed `node` path Also snuck in a mention of WHAT to open in Xcode (the workspace, not the project). The `postinstall.sh` prebuild hooks are also changed from `eval` to `bash -c` so they run in a clean shell without inheriting `set -eo pipefail` from the parent script. Previously, if the hook's SSH clone failed, the parent's `set -e` would kill the process before the hook's own HTTPS fallback could run. The hooks now also surface a warning with the manual command instead of silently failing.
1 parent 842751a commit a8ab370

2 files changed

Lines changed: 65 additions & 59 deletions

File tree

‎README.md‎

Lines changed: 53 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -60,70 +60,70 @@ Set up these **before** running `yarn install`, as the postinstall script reads
6060
The iOS `GoogleService-Info.plist` is already in the repo and gets its API key
6161
patched by the postinstall script from `GOOGLE_SERVICE_API_KEY` in your `.env`.
6262

63-
### MacOS
63+
### iOS (macOS only)
6464

65-
1. Install the [latest version of XCode](https://developer.apple.com/xcode/).
66-
67-
2. Install Watchman:
68-
69-
```shell
70-
brew install watchman
65+
1. Install Xcode from the Mac App Store.
66+
2. Install Watchman: `brew install watchman`
67+
3. Install the required bundles and Pods:
7168
```
72-
73-
3. Install the required bundles (including CocoaPods) and Pods for this project:
74-
```shell
7569
yarn install-bundle && yarn install-pods
7670
```
7771

78-
### Linux
72+
### Android
7973

80-
1. Install system dependencies:
81-
82-
```shell
83-
sudo apt install libsecret-tools watchman
74+
1. Install JDK 17. Do **not** use the JDK bundled with Android Studio (it's
75+
JDK 21, which [causes build
76+
failures](https://reactnative.dev/docs/set-up-your-environment)). On macOS:
77+
```sh
78+
brew install --cask zulu@17
8479
```
85-
86-
2. Follow the [React Native environment setup
87-
instructions](https://reactnative.dev/docs/environment-setup) carefully,
88-
which will involve installing Android Studio, the Android SDK, the emulator,
89-
etc. and making them available in your `$PATH`.
90-
91-
3. Ensure at least one [AVD
92-
image](https://developer.android.com/studio/run/managing-avds) is available
93-
for the emulator (unless using a physical device).
94-
95-
## Developing
96-
97-
If you are new to React Native, this is a helpful introduction:
98-
https://reactnative.dev/docs/getting-started
99-
100-
### MacOS
101-
102-
_Note: Darwin versions of the application can only be developed/built on Darwin
103-
platforms with XCode._
104-
105-
1. Start a React Native webserver with:
106-
107-
```shell
108-
yarn start
80+
2. Add to your shell profile (`~/.zshrc` or `~/.bashrc`):
81+
82+
```sh
83+
export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
84+
export ANDROID_HOME=$HOME/Library/Android/sdk # macOS
85+
# export ANDROID_HOME=$HOME/Android/Sdk # Linux
86+
export PATH=$PATH:$ANDROID_HOME/emulator
87+
export PATH=$PATH:$ANDROID_HOME/platform-tools
10988
```
11089

111-
2. Open `rainbow-wallet/ios/Rainbow.xcworkspace` in XCode.
112-
113-
3. Run the project by clicking the play button.
90+
On Linux, also install system dependencies: `sudo apt install libsecret-tools watchman`
91+
92+
3. Install [Android Studio](https://developer.android.com/studio) (the standard
93+
setup wizard is fine).
94+
4. Increase the IDE memory: **Android Studio > Settings > Memory Settings** and
95+
set the heap to at least 4096 MB. This project is large enough that the
96+
default 2048 MB will cause slow syncs and builds.
97+
5. Set the Gradle JDK: **Settings > Build, Execution, Deployment > Build
98+
Tools > Gradle > Gradle JDK** and select the `JAVA_HOME` (Azul Zulu 17)
99+
entry. The default points to the bundled JDK 21.
100+
6. Restart any open terminals so the new environment variables take effect.
101+
7. Create an emulator via Android Studio > Device Manager (unless using a physical device).
102+
8. Run the first build from the terminal to generate native headers that
103+
Android Studio needs for Gradle sync:
104+
```
105+
cd android && ./gradlew assembleDebug && cd ..
106+
```
107+
9. Quit Android Studio completely, then reopen it from the terminal so Gradle
108+
sync picks up the generated headers:
109+
```
110+
open -a "Android Studio" # macOS
111+
```
112+
Always launch Android Studio this way so it inherits your shell PATH
113+
(including `node` from nvm). Launching from Spotlight or the Dock will
114+
cause Gradle sync to fail with "Cannot run program node".
114115

115-
### Linux
116+
## Developing
116117

117-
_Note: Linux development environments cannot develop or build Darwin versions of the
118-
project._
118+
Start Metro in one terminal:
119119

120-
1. Start a React Native webserver with:
120+
```
121+
yarn start
122+
```
121123

122-
```shell
123-
yarn start
124-
```
124+
Then build and run:
125125

126-
2. Build/install/start the debug version of the app in an emulator with:
127-
```shell
128-
yarn android
129-
```
126+
- **iOS:** Open `ios/Rainbow.xcworkspace` in Xcode (not the `.xcodeproj`) and
127+
press Cmd+R, or run `yarn ios` from the terminal.
128+
- **Android:** Open the `android/` folder in Android Studio, or run
129+
`yarn android` from the terminal.

‎scripts/postinstall.sh‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -86,19 +86,25 @@ fi
8686

8787
if [ -n "$RAINBOW_SCRIPTS_APP_IOS_PREBUILD_HOOK" ]; then
8888
if [ -n "$CI" ]; then
89-
eval $RAINBOW_SCRIPTS_APP_IOS_PREBUILD_HOOK > /dev/null 2>&1;
89+
bash -c "$RAINBOW_SCRIPTS_APP_IOS_PREBUILD_HOOK" > /dev/null 2>&1;
9090
else
91-
eval $RAINBOW_SCRIPTS_APP_IOS_PREBUILD_HOOK;
92-
echo "✅ executed ios prebuild hook"
91+
if bash -c "$RAINBOW_SCRIPTS_APP_IOS_PREBUILD_HOOK"; then
92+
echo "✅ executed ios prebuild hook"
93+
else
94+
echo "⚠️ ios prebuild hook failed — run it manually: $RAINBOW_SCRIPTS_APP_IOS_PREBUILD_HOOK"
95+
fi
9396
fi
9497
fi
9598

9699
if [ -n "$RAINBOW_SCRIPTS_APP_ANDROID_PREBUILD_HOOK" ]; then
97100
if [ -n "$CI" ]; then
98-
eval $RAINBOW_SCRIPTS_APP_ANDROID_PREBUILD_HOOK > /dev/null 2>&1;
101+
bash -c "$RAINBOW_SCRIPTS_APP_ANDROID_PREBUILD_HOOK" > /dev/null 2>&1;
99102
else
100-
eval $RAINBOW_SCRIPTS_APP_ANDROID_PREBUILD_HOOK;
101-
echo "✅ executed android prebuild hook"
103+
if bash -c "$RAINBOW_SCRIPTS_APP_ANDROID_PREBUILD_HOOK"; then
104+
echo "✅ executed android prebuild hook"
105+
else
106+
echo "⚠️ android prebuild hook failed — run it manually: $RAINBOW_SCRIPTS_APP_ANDROID_PREBUILD_HOOK"
107+
fi
102108
fi
103109
fi
104110

0 commit comments

Comments
 (0)