From 2b4c3e3e50b7b7475a37ba38c234e9bc5bb29cdd Mon Sep 17 00:00:00 2001 From: Pierre Tessier Date: Sun, 22 Dec 2024 20:47:39 -0500 Subject: [PATCH 1/3] cleanup build instructions --- src/react-native-app/README.md | 143 +++++++++++++++++---------------- 1 file changed, 75 insertions(+), 68 deletions(-) diff --git a/src/react-native-app/README.md b/src/react-native-app/README.md index 88b2bd3b87..261c9f6910 100644 --- a/src/react-native-app/README.md +++ b/src/react-native-app/README.md @@ -1,6 +1,7 @@ # Example React Native app -This was created using [`npx create-expo-app@latest`](https://reactnative.dev/docs/environment-setup#start-a-new-react-native-project-with-expo) +This was created using +[`npx create-expo-app@latest`](https://reactnative.dev/docs/environment-setup#start-a-new-react-native-project-with-expo) Content was taken from the web app example in src/frontend and modified to work in a React Native environment. @@ -17,102 +18,124 @@ make start # or start-minimal ## Building the app Unlike the other components under src/ which run within containers this -app must be built and then run on a mobile simulator on your machine or a physical -device. If this is your first time running a React Native app then in order to -execute the steps under "Build on your host machine" you will need to setup your -local environment for Android or iOS development or both following -[this guide](https://reactnative.dev/docs/set-up-your-environment). Alternatively -for Android you can instead follow the steps under "Build within a container" to -leverage a container to build the app's apk for you. +app must be built and then run on a mobile simulator on your machine or a +physical device. If this is your first time running a React Native app then in +order to execute the steps under "Build on your host machine" you will need to +setup your local environment for Android or iOS development or both following +[this guide](https://reactnative.dev/docs/set-up-your-environment). Alternatively for Android you can instead follow the steps +under "Build within a container" to leverage a container to build the app's apk +for you. ### Build on your host machine -Build and run the React Native app for a given platform by navigating to this folder -and running: +Before building the app you will need to install the dependencies for the app. ```bash cd src/react-native-app npm install ``` -To run on Android: +#### Android: Build and run app + +To run on Android, the following command will compile the Android app and deploy +it to a running Android simulator or connected device. It will also start a +a server to provide the JS Bundle required by the app. ```bash npm run android ``` -Note that for the above command a server is also spun up to serve the JS bundle -to the deployed app. +#### iOS: Setup dependencies -To run on iOS you may find it cleanest to build through the XCode IDE. First spin -up the react native dev server with the following (feel free to ignore the output -commands referring to opening an iOS simulator, we'll do that directly through -XCode in a later step): +Before building for iOS you will need to setup the iOS dependency management +using CocoaPods. This command only needs to be run the first time before +building the app for iOS. ```bash -npm run start +cd ios && pod install && cd .. ``` -Then install the pods for the project: +#### iOS: Build and run with XCode -```bash -cd ios -pod install -``` - -Note that the above is the quickest way to get going but you may end up with -slightly different versions of the Pods than what has been committed to this repo, -in order to install the precise versions first setup [rbenv](https://github.com/rbenv/rbenv#installation) -followed by: +To run on iOS you may find it cleanest to build through the XCode IDE. In order +to start a server to provide the JS Bundle, run the following command (feel free +to ignore the output commands referring to opening an iOS simulator, we'll do +that directly through XCode in the next step). ```bash -rbenv install 2.7.6 # the version of ruby we've pinned for this app -bundle install -cd ios -bundle exec pod install +npm run start ``` -Then open XCode, open this as an existing project by opening `src/react-native-app/ios/react-native-app.xcworkspace` -then trigger the build by hitting the Play button or from the menu using Product->Run. +Then open XCode, open this as an existing project by opening +`src/react-native-app/ios/react-native-app.xcworkspace` then trigger the build +by hitting the Play button or from the menu using Product->Run. + +#### iOS: Build and run from the command-line -Or alternatively build and run from the command-line: +You can build and run the app using the command line with the following +command. This will compile the iOS app and deploy it to a running iOS simulator +and start a server to provide the JS Bundle. ```bash npm run ios ``` -Note that for the above command a server is also spun up to serve the JS bundle -to the deployed apps. - ### Build within a container For Android builds you can produce an apk using Docker without requiring the dev -tools to be installed on your host. From the project root run: +tools to be installed on your host. From this repository root run the +following command. ```bash make build-react-native-android ``` -Or directly from this folder using: +Or directly from this folder using. ```bash docker build -f android.Dockerfile --platform=linux/amd64 --output=. . ``` -This will produce `react-native-app.apk` in the directory where you ran the command. -If you have an Android emulator running on your machine then you can simply drag -and drop this file onto the emulator's window in order to install it following +This will produce `react-native-app.apk` in the directory where you ran the +command. If you have an Android emulator running on your machine then you can +simply drag and drop this file onto the emulator's window in order to install it +following [these steps](https://developer.android.com/studio/run/emulator-install-add-files). -TODO: For a physical device you can install this by sending the apk file to your -device, giving the "Install unknown apps" permission to the app you will be opening -the file with, and then installing it. However this won't be able to hit the APIs -because they are hard-coded to be localhost, need those to be configurable before -this method would work. - ## Troubleshooting -### iOS build issues +### JS Bundle: build issues + +Try removing the `src/react-native-app/node_modules/` folder and then re-run +`npm install` from inside `src/react-native-app`. + +### Android: build app issues + +Try stopping and cleaning local services (in case there are unknown issues +related to the start of the app). + +```bash +cd src/react-native-app/android +./gradlew --stop // stop daemons +rm -rf ~/.gradle/caches/ +``` + +### iOS: pod install issues + +Note that the above is the quickest way to get going but you may end up with +slightly different versions of the Pods than what has been committed to this +repository, in order to install the precise versions first setup +[rbenv](https://github.com/rbenv/rbenv#installation) followed by the following +commands. + +```bash +rbenv install 2.7.6 # the version of ruby we've pinned for this app +bundle install +cd ios +bundle exec pod install +``` + +### iOS: build app issues If you see a build failure related to pods try forcing a clean install with and then attempt another build after: @@ -126,25 +149,9 @@ then attempt another build after: pod install --repo-update --verbose ``` -If there is an error compiling or running the app try closing any open simulators -and clearing all derived data: +If there is an error compiling or running the app try closing any open +simulators and clearing all derived data: ```bash rm -rf ~/Library/Developer/Xcode/DerivedData ``` - -### Android build issues - -Try stopping and cleaning local services (in case there are unknown issues related -to the start of the app): - -```bash - cd src/react-native-app/android - ./gradlew --stop // stop daemons - rm -rf ~/.gradle/caches/ -``` - -### JS build issues - -Try removing the `src/react-native-app/node_modules/` folder and then re-run -`npm install` from inside `src/react-native-app`. From 01dbb86f3cc2d284183061cf77fd1d3820422f8c Mon Sep 17 00:00:00 2001 From: Pierre Tessier Date: Sun, 22 Dec 2024 20:52:22 -0500 Subject: [PATCH 2/3] cleanup build instructions --- src/react-native-app/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/react-native-app/README.md b/src/react-native-app/README.md index 261c9f6910..87bcc81bd8 100644 --- a/src/react-native-app/README.md +++ b/src/react-native-app/README.md @@ -22,9 +22,9 @@ app must be built and then run on a mobile simulator on your machine or a physical device. If this is your first time running a React Native app then in order to execute the steps under "Build on your host machine" you will need to setup your local environment for Android or iOS development or both following -[this guide](https://reactnative.dev/docs/set-up-your-environment). Alternatively for Android you can instead follow the steps -under "Build within a container" to leverage a container to build the app's apk -for you. +[this guide](https://reactnative.dev/docs/set-up-your-environment). +Alternatively for Android you can instead follow the steps under "Build within a +container" to leverage a container to build the app's apk for you. ### Build on your host machine From 9fe09c639b28a8687a834254f8f80328b9e22c54 Mon Sep 17 00:00:00 2001 From: Pierre Tessier Date: Sun, 22 Dec 2024 21:14:54 -0500 Subject: [PATCH 3/3] cleanup build instructions --- src/react-native-app/README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/react-native-app/README.md b/src/react-native-app/README.md index 87bcc81bd8..0c9eb2c1dd 100644 --- a/src/react-native-app/README.md +++ b/src/react-native-app/README.md @@ -96,11 +96,9 @@ Or directly from this folder using. docker build -f android.Dockerfile --platform=linux/amd64 --output=. . ``` -This will produce `react-native-app.apk` in the directory where you ran the -command. If you have an Android emulator running on your machine then you can -simply drag and drop this file onto the emulator's window in order to install it -following -[these steps](https://developer.android.com/studio/run/emulator-install-add-files). +This will create a `react-native-app.apk` file in the directory where you ran +the command. If you have an Android emulator running on your machine then you +can drag and drop this file onto the emulator's window in order to install it. ## Troubleshooting