From ec1e3d996a5c41f83a61b7e7c78c878c3a515fd1 Mon Sep 17 00:00:00 2001 From: Taea <88346289+adrastaea@users.noreply.github.com> Date: Thu, 16 May 2024 12:01:02 -0400 Subject: [PATCH] Update Mobile New Dev Docs (#2485) * update README.md with more detailed steps * fix Gemfile formatting * finalize readme * update changelog * update links and fix md lint errors --- CHANGELOG.md | 1 + packages/mobile/Gemfile | 5 +- packages/mobile/README.md | 236 +++++++++++++++++++++++++++++++------- 3 files changed, 198 insertions(+), 44 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bed72c3a3f..220e69a845 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ # Chores * Cleanup data directory at end of e2e tests +* Update mobile development README ([#2483](https://github.com/TryQuiet/quiet/issues/2483)) * Update github workflows for PR gating ([#2487](https://github.com/TryQuiet/quiet/issues/2487)) * Don't create duplicate CSRs when joining a community under certain circumstances ([#2321](https://github.com/TryQuiet/quiet/issues/2321)) * Add abstract base classes for stores ([#2407](https://github.com/TryQuiet/quiet/issues/2407)) diff --git a/packages/mobile/Gemfile b/packages/mobile/Gemfile index 56d517457a..0bfc7e6536 100644 --- a/packages/mobile/Gemfile +++ b/packages/mobile/Gemfile @@ -1,4 +1,5 @@ -gem 'activesupport', '>= 6.1.7.3', '< 7.1.0'source 'https://rubygems.org' +source 'https://rubygems.org' +gem 'activesupport', '>= 6.1.7.3', '< 7.1.0' # You may use http://rbenv.org/ or https://rvm.io/ to install and use this version ruby ">= 2.6.10" -gem 'cocoapods', '~> 1.13' \ No newline at end of file +gem 'cocoapods', '~> 1.13' diff --git a/packages/mobile/README.md b/packages/mobile/README.md index 39efa174dd..c4a9bcd16c 100644 --- a/packages/mobile/README.md +++ b/packages/mobile/README.md @@ -6,46 +6,103 @@ Quiet Mobile is a React Native app for Android and iOS that shares a Node.js [ba ### Prerequisites -Install `patch` (e.g. via your Linux package manager). +1. If not on Mac (which comes preinstalled with `patch`), install `patch` (e.g. via your Linux package manager). -In the root directory of `quiet/`, install the monorepo's dependencies and bootstrap the project with lerna. It will take care of the package's dependencies and trigger a prepublish script which builds them. +1. In the root directory of `quiet/`, install the monorepo's dependencies and bootstrap the project with lerna. It will take care of the package's dependencies and trigger a prepublish script which builds them. -``` -npm install -npm run lerna bootstrap -``` + ```bash + npm install + npm run lerna bootstrap + ``` + +1. On your host, install [adb](https://developer.android.com/studio/command-line/adb) (Android Debug Bridge) to communicate with your Android device. + +1. If running on a physical device, enable USB debugging on your device and connect it to your computer via USB. If running on an emulator, start the emulator. + + [React Native: Running on Device](https://reactnative.dev/docs/running-on-device) + [Android Developers: Configure Developer Options](https://developer.android.com/studio/debug/dev-options) + +1. Add the path to the java binary installed by Android Studio JAVA_HOME to your environment variables. Ensure that you have followed the SDK installation instructions in the [React Native Development Environment](https://reactnative.dev/docs/set-up-your-environment) guide. + + For example, on macOS with Android Studio installed in the default location, + Add the following line to your `~/.bash_profile` or `~/.zprofile` file, + + ```bash + export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home" + ``` + +### Local development + +Follow the steps in [React Native Development Environment](https://reactnative.dev/docs/set-up-your-environment) to set up your development environment. + +#### Running Android App from Command Line -On your host, install adb, https://developer.android.com/studio/command-line/adb. +1. After following the React Native Development Environment instructions, navigate to the `packages/mobile` directory and run the application, -On your phone in the Developer Options, enable USB debugging (check carefully for security options as they may appear besides the standard debugging ones) and enable installing applications through USB on your physical device (https://developer.android.com/studio/debug/dev-options) and plug in your phone via USB cable. + ```bash + npm run android + ``` + + The application should now be running on your device. + +#### Running from Android Studio + +1. Open the `android` directory in Android Studio. +1. If necessary, sync the Gradle files by hitting the "Sync Project with Gradle Files" button in the top right corner. +1. Select the target device or emulator and press the play button. ### Docker container Docker container with Android development environment can be found in `packages/mobile/android-environment`. -Build the image, +1. Build the image, -``` -docker build -t quiet-mobile-dev -f Dockerfile . -``` + ```bash + # From packages/mobile/android-environment + docker build -t quiet-mobile-dev -f Dockerfile . + ``` -Then start a container and attach to it, +1. Export an environment variable with the path to the root of the repository, -``` -docker run -it --rm --name quiet-mobile-debug -u node --network host --entrypoint bash --privileged -v /dev/bus/usb:/dev/bus/usb -v /:/app quiet-mobile-dev -``` + For bash, -Once attached to the container, start Metro, a JavaScript bundler for React Native, + ```bash + # From the root of the repository + echo "export QUIET_REPO_ROOT=$(pwd)" >> ~/.bash_profile + source ~/.bash_profile + ``` -``` -npm run start -``` + or for zsh -Open another terminal window and start building the application, + ```bash + # From the root of the repository + echo "export QUIET_REPO_ROOT=$(pwd)" >> ~/.zprofile + source ~/.zprofile + ``` -``` -docker exec -it quiet-mobile-debug /usr/local/bin/npm run android -``` +1. Then start a container and attach to it, + + ```bash + docker run -it --rm --name quiet-mobile-debug -u node --network host --entrypoint bash --privileged -v /dev/bus/usb:/dev/bus/usb -v $QUIET_REPO_ROOT:/app quiet-mobile-dev + ``` + + Your command line should now look like `node@docker-desktop:/app/packages/mobile$` + +1. Once attached to the container, start Metro, a JavaScript bundler for React Native, + + ```bash + npm run start + ``` + + Warning: Do not select any options in the Metro terminal window. + +1. Open another terminal window and start building the application, + + ```bash + docker exec -it quiet-mobile-debug /usr/local/bin/npm run android + ``` + + The application should now be running on your device. ### Wireless debugging (optional) @@ -55,13 +112,13 @@ To connect your debugging device wirelessly, make sure it runs on Android 11 or Open a terminal window and tell the adb daemon to use port 5555, -``` +```bash adb tcpip 5555 ``` Then check your phone's IP address and connect to it -``` +```bash adb connect :5555 ``` @@ -71,7 +128,7 @@ Unplug your phone and repeat the last command in the Docker container section to Open a terminal window, -``` +```bash adb logcat --pid=$(adb shell pidof -s com.quietmobile.debug) ``` @@ -79,18 +136,95 @@ adb logcat --pid=$(adb shell pidof -s com.quietmobile.debug) Metro requires additional step for locally linking packages. After running standard `npm link` commands, update `metro.config.js` as follows -``` +```bash const watchFolders = [ ... path.resolve(__dirname, '') ] ``` +## Setting up iOS environment + +### Prerequisites for iOS development + +1. Install [Xcode](https://developer.apple.com/xcode/) from the Mac App Store. +1. Follow the [React Native Development Environment](https://reactnative.dev/docs/set-up-your-environment) instructions to set up your development environment. +1. Install rbenv, a Ruby version manager. + + ```bash + brew install rbenv + ``` + +1. Set your Ruby version to the suggested version. + + At the time of writing, the suggested Ruby version is 2.7.5 + + ```bash + rbenv install 2.7.5 + rbenv global 2.7.5 + ``` + +1. Install ruby dependencies from the Gemfile in the `packages/mobile` directory. + + ```bash + gem install bundler + bundle install + ``` + +1. Install the pods for the iOS project. + + ```bash + cd ios + bundle exec pod install + ``` + +1. Open the `ios` directory in Xcode. + +1. If planning to run on device, setup the signing certificate and provisioning profile in Xcode. + + [React Native: Running on Device](https://reactnative.dev/docs/running-on-device) + +### Running iOS App With Command Line + +1. Start the Metro bundler, + + From the `packages/mobile` directory, + + ```bash + npm run start + ``` + +1. Build and run the application, + + From the `packages/mobile` directory, + + ```bash + npm run ios + ``` + + or from Xcode, select the target device and press the play button. + + The application should now be running on your device. + +### Xcode + +1. Start the metro bundler, + + From the `packages/mobile` directory, + + ```bash + npm run start + ``` + +1. Open the `ios` directory in Xcode. +1. Select the target device or simulator and press the play button. + ## Running E2E tests (optional) -We use Detox (https://wix.github.io/Detox/) for E2E testing on mobile. + +We use [Detox](https://wix.github.io/Detox/) for E2E testing on mobile. Detox recommends to install its `detox-cli` globally, enabling usage of the command line tools outside npm scripts. -``` +```bash npm install detox-cli --global ``` @@ -104,18 +238,18 @@ There're two commands to use: The first one for building binary file to put under test: -``` +```bash detox build --configuration android.att.debug ``` And the second one for actually running the tests: (let's trigger the basic set of e2e tests called `starter`) -``` +```bash detox test starter --configuration android.att.debug ``` -For more detailed instructions, see https://wix.github.io/Detox/docs/introduction/your-first-test/ +For more detailed instructions, see [Detox:Your First Test](https://wix.github.io/Detox/docs/introduction/your-first-test/) ## Running visual regression tests @@ -130,7 +264,7 @@ In order to perform comparision, the presence of a base screenshots is required There're two types of tests: a basic (starter) set of e2e tests, and an app-wide visual regression test which uses storybook. For the second type, it's important to use a `storybook` variant of the build -``` +```bash detox test storybook --configuration android.att.storybook -- -enable-visual-regression ``` @@ -145,7 +279,6 @@ React-native projects consists of two parts: javascript code and native code. Na If you only wish to make changes to the react-native part of the project, simply use your favorite code editor. Altough if you plan to modify the native code, Android Studio is recommended as it simplifies things a lot and Xcode is required to be able to work with iOS. - ### When to rebuild the project? Both Android and iOS manages their own dependencies with the help of `gradle` (Android) and `cocoapods` (iOS). They work similar to `npm`. @@ -155,29 +288,31 @@ If changes are made to the native part of the project (java, kotlin, objc or swi React-native uses a tool called metro to bundle javascript files. It does it on runtime, before processing react-native code. Depending on the size of cached files it may take several seconds to fully load the bundled js code. When a change is made to the javascript codebase, it's usually enough to reload files with metro, by pressing `R` from within the console in which metro operates. - ### Access iOS simulator files system + Find proper directory by running -``` + +```bash xcrun simctl get_app_container booted com.quietmobile data ``` -enter it and find directory data within `/Documents` folder +enter it and find directory data within `/Documents` folder ### The app is stuck on splash screen Sometimes metro loader takes long enough to cause a race condition failure with the native service notifying javascript code about the data of websocket server we use to communicate with backend. In this case, we should be able to observe a log informing us that an event has been emitted but there was nothing to receive it: -``` + +```bash WEBSOCKET CONNECTION: Starting on 11000 RCTNativeAppEventEmitter: Tried to send an event but got NULL on reactContext ``` + The easiest solution is to close the app and open it again by tapping it's icon on the device (there's no need to rebuild the project) (Android/iOS) or to follow `Product -> Perform Action -> Run Without Building` in Xcode. (iOS) If it's not enough, you can locally increase the `WEBSOCKET_CONNECTION_DELAY` for emitting the event at `mobile/android/app/src/main/java/com/quietmobile/Utils/Const.kt` (Android) - ## Troubleshooting ### Could not set file mode 644 on @@ -195,6 +330,23 @@ Built app bundle cannot contain symlinks linking outside the package (which some ### Unable to resolve module Usage of native methods (like the ones for file management) must be adapted for mobile environment. There're several ways to fix the issue with incompatible packages/files: -1. Shim packages with `rn-dodeify` https://www.npmjs.com/package/rn-nodeify + +1. Shim packages with `rn-dodeify` 2. Blacklist certain files in `metro.config.js:30` -3. Use diff & patch https://www.freecodecamp.org/news/compare-files-with-diff-in-linux/ +3. Use diff & patch + +### Process already running on :8081 + +If you encounter a problem with metro bundler, make sure there's no other process running on the same port. If it's the case, kill the process and try again. + +Get the PID of the process: + +```bash +lsof -i :8081 +``` + +Kill the process: + +```bash +kill -9 +```