How to Build mushroom-observer-mobile for iPhone and Android

[mo-nathan]

Pre-requisites

This section depends on the operating system of the computer you plan on working on.

Download Build Environments: MacOSX iPhone

1. Go to the App Store and install Xcode. My current version of Xcode is 15.2 and I'm running MacOS Sonoma 14.2.1. These notes were created using a freshly made user account with admin permissions.
2. Start up Xcode and ensure that you enable building for iOS.
3. Startup a Terminal window (Terminal is an application in Application -> Utilities. You can also press Cmd-Space to bring up Spotlight and type in "Terminal".)
4. Type xcode-select --install into the Terminal window to install the Xcode command line tools.

Download Build Environment: Android

1. Download Android Studio from the web. I was not able to find it in the App Store. You should be able to download from here: https://developer.android.com/studio. These instructions were created and verified using the Hedgehog Patch 2 release. Make sure you select the correct chip for your local machine.
2. Install Android Studio.
3. Use all the default settings and accept all the licenses.

Create Your Local mushroom-observer-mobile Code Repo

If you are an experienced GitHub user you can just clone the public repo with:
git clone [email protected]:MushroomObserver/mushroom-observer-mobile.git and go to the next section.

Otherwise, if you are using Xcode you can do the following:

1. Ensure that git has been installed. You can do that in your Terminal window with the command git --version. It should respond with something like git version 2.39.3 (Apple Git-145). There version of git should not matter.
2. Returning to Xcode select "Clone Git Repository...". This assumes you already have an account on GitHub. If you don't, go to https://github.com in a web browser (e.g., Safari) and "Sign Up" for a new account. If the initial project creation dialog is not visible. you can select Integrate -> Clone...
3. Click the -> in a circle to "Add Hosted Account".
4. Click + on the Accounts page (bottom left corner).
5. Select GitHub.
6. Enter your GitHub account name and click Create a Token on GitHub. This will take you to a page in your default browser.
7. Enter a description. You might want to extend the expiration if you plan to use this for a while, but you can also go with the default (30 days) and renew it when it expires.
8. Select the scopes suggested by Xcode. Note that they may not be in the same order. On GitHub at the moment the order is: "repo", "admin:public_key", "user", "write:discussion". Click "Generate token" at the bottom of the page.
9. Copy the token and paste it into the dialog box in the Accounts page for Xcode and click "Sign In".
10. In the Xcode window search for Mushroom Observer and double click on "mushroom-observer-mobile". Then click 'Clone" and then "Clone" again. DO NOT CHECK IT OUT IN THE DEFAULT DIRECTORY: Documents. This directory has weird permissions that seem to mess with the ability to correctly run the simulator. You can use your home directory or your Desktop directory.

If you are not using Xcode, go to https://github.com and sign up for an account. You will need to install some sort of local git client. Many IDEs support git and there is an easy to use command line version that may already be on your system. You will need to setup an SSH key in GitHub which is discussed on the GitHub website. Once you have the account and local access to git you will want to clone the MushroomObserver/mushroom-observer-mobile repository. Again from the command line the command is:
git clone [email protected]:MushroomObserver/mushroom-observer-mobile.git

Getting the Right Version of Node Installed

First install the latest version of Node.js. On a Mac I recommend using Homebrew for this. On other systems there may be other package managers you want to use for this. You can also download it from the Node.js website (https://nodejs.org/en/download). The downside of downloading it yourself is maintaining it can be more of pain.

To install Node using Homebrew:

1. Switch back to your Terminal window and change to the new "mushroom-observer-mobile" directory. For me the command was cd ~/mushroom-observer-mobile.
2. Installing Homebrew requires admin access and should only be done with an account you expect to keep. The instructions are on the main webpage for Homebrew, https://brew.sh.
3. Once you have Homebrew installed, from an admin account run brew install node.
4. Update your .zprofile by running echo 'eval $($HOMEBREW_PREFIX/bin/brew shellenv)' >> ~/.zprofile.
5. Now in a new Terminal window, ensure that which node and which npm return something.
6. The current code base requires an old version of node. To manage multiple versions of node, I recommend the Node Version Manager (NVM) which is maintained here: https://github.com/nvm-sh/nvm. To install it run curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash.
7. In a new Terminal window, now run nvm list. This should give you something like:

% nvm list

->       system
iojs -> N/A (default)
node -> stable (-> N/A) (default)
unstable -> N/A (default)

8. From your mushroom-observer-mobile directory (cd ~/mushroom-observer-mobile) install version 16.20.2 with nvm install 16.20.2. Now running nvm list should give you something like:

% nvm list
->     v16.20.2
         system
default -> 16.20.2 (-> v16.20.2)
iojs -> N/A (default)
unstable -> N/A (default)
node -> stable (-> v16.20.2) (default)
stable -> 16.20 (-> v16.20.2) (default)
lts/* -> lts/iron (-> N/A)
lts/argon -> v4.9.1 (-> N/A)
lts/boron -> v6.17.1 (-> N/A)
lts/carbon -> v8.17.0 (-> N/A)
lts/dubnium -> v10.24.1 (-> N/A)
lts/erbium -> v12.22.12 (-> N/A)
lts/fermium -> v14.21.3 (-> N/A)
lts/gallium -> v16.20.2
lts/hydrogen -> v18.19.1 (-> N/A)
lts/iron -> v20.11.1 (-> N/A)

9. Install Node packages. In a Terminal window switch do the mushroom-observer-mobile directory created when you cloned the GitHub repo. For me cd ~/mushroom-observer-mobile. Now run npm install. You should see some deprecation warnings, some vulnerability warnings, and a recommendation to upgrade npm. Don't worry about any of those.

Setting Up Your .env Files

1. In the mushroom-observer-mobile directory copy .env.template to .env.production and .env.development: cp .env.template .env.production; cp .env.template .en.development. You need the .env.production to support a current "Run pre-action" in Xcode which should probably not be what it is. (To find this, after loading MushroomObserver.xcworkspace I had to click on the Mushroom Observer drop down in the top bar, select "Edit Scheme...", expand "Build" on the left side of Edit Scheme dialog, and click "Pre actions".)
2. If you are running a local version of the MO website, you should probably update the MUSHROOM_OBSERVER_API_URL to be http://10.0.2.2:3000. Otherwise, you can use https://mushroomobserver.org to go to the live website.
3. In the .env files set MUSHROOM_OBSERVER_API_KEY to one you create on your local development server or the live site
   • To create an API key, go to https://mushroomobserver.org/account/api_keys. You can navigate there from your Mushroom Observer account preferences and then click "API Key Manager".
   • Enter a name for your API key and then click "Create a New Key"
   • Use the new key as your app's API key
4. I'm not convinced that GOOGLE_MAPS_API_KEY matters. If you need one you may need to give Google your credit card even if you don't plan to use it for anything other than development.

mushroom-observer-mobile Setup for the iPhone Build

1. From the ios directory run bundle install --path vendor/bundle.
2. Address any reported errors. For me it reported:

Ignoring nio4r-2.5.8 because its extensions are not built. Try: gem pristine nio4r --version 2.5.8
Ignoring websocket-driver-0.7.5 because its extensions are not built. Try: gem pristine websocket-driver --version 0.7.5

Both of these commands required sudo to run for me, but that might be something weird in how something got setup previously.
7. Install cocoapods: sudo gem install cocoapods. Takes a while. Address any errors
8. Run pod install
9. From the Finder now open (double-click) on the file "MushroomObserver.xcworkspace". This should be under the mushroom-observer-mobile directory created when you cloned the GitHub repo in the ios subdirectory. I created this directory in my home directory. You should also be able to find it with Spotlight (Cmd-Space, type in the name).
11. Click the triangular arrow button at the top of the window.
12. Currently this fails with the error: "Yoga: Use of bitwise '|' with boolean operands". This is a known issue with the version of the Yoga layout manager we're using when compiled against the latest compiler in Xcode. It should show you the file with the issue and recommend that you replace '|' with '||'. This is the correct fix. This problem should go away when we get to a more recent version of React Native. Make the fix and ensure the file is saved. Click the run arrow again.
13. The next failure is "No template named 'unary_function' in namespace 'std'" in hash.hpp. This is due to another Xcode change. This can be solved by replacing "unary_function" with "__unary_function".
14. The simulator should now launch. It may request access to your working folder for "watchman". Allow this access. Xcode will launch metro in a terminal window.

mushroom-observer-mobile Setup for the Android Build

1. Download Android Studio from the web. I was not able to find it in the App Store. You should be able to download from here: https://developer.android.com/studio. These instructions were created and verified using the Hedgehog Patch 2 release. Make sure you select the correct chip for your local machine.
2. You may want to shutdown Xcode and the iPhone Simulator if you have those running to reduce the load on your system.
3. Install Android Studio.
4. Use all the default settings and accept all the licenses.
5. Click "Open" when you get to the Welcome to Android Studio screen. Select your mushroom-observer-mobile/android folder and click "Trust Project".
6. The project currently uses an old version of Gradle to build the app. This requires and older version of the Java (11) and the Kotlin (1.8) languages. To confirm you have the correct version of Gradle selected, go to File -> Project Structure... Ensure that "Project" is selected on the left side of the screen. The right side should say Android Gradle Plugin Version 4.2.2, Gradle Version 6.9.
7. Select Java 11. Go to Android Studio -> Settings. Expand Build, Execution, Deployment, then expand Build Tools. Select Gradle. For the Gradle JDK select Download JDK. Select Version 11. I don't know that the version of the Java 11 JDK matters, but I selected Azul Zulu Community 11.0.22 aarch64 (I'm on an Apple M1 chip). Click "Download" then "Okay". At the bottom of the screen there should be progress bar. Wait until that completes.
8. In the main window in the lower left, click on the build icon (hammer) and click the "Reload Gradle Project" icon. It will take a while, but it should eventually say "BUILD SUCCESSFUL". It reported 5m 38s for me.
9. It should have automatically created and selected a phone for the emulator. If not, select the "Device Manager" icon on the far right and add a device. There are lots of options. Most recently I've been using a Medium Phone with Android 14/UpsideDownCake. Now go to the "Running Devices" icon on the right side of the screen and click the run triangle next to the device you just created. You should see simulated phone appear on the right side of the screen.
10. To get Metro working for dynamic packaging, in a new Terminal window got to the top of your local GitHub repo (in for me cd ~/mushroom-observer-mobile). The run adb reverse tcp:8081 tcp:8081, followed by npx react-native start to create the Metro process. This should allow Android Studio to automatically connect to the Metro process.
11. If you can't get Metro working or you want to work with a precompiled bundle, first make sure the directory android/app/src/main/assets exists. If it doesn't run mkdir android/app/src/main/assets. Then run react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res. Once that's done you should be able to click the run triangle in the top toolbar (next to "app") and it should start up the app for you in your emulated cell phone.

You should get to the login screen and be able to see the "Register" page. However, I have not been able to get it to actually talk to the website. I'm thinking it has something to do with the information (keys) in the .env file not getting read.