diff --git a/Build_ss.png b/Build_ss.png new file mode 100644 index 000000000..18ab48b23 Binary files /dev/null and b/Build_ss.png differ diff --git a/README.md b/README.md index 0c02868db..e267f8e71 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,61 @@ -e-mission phone app --------------------- +# [e-mission phone app](https://github.com/e-mission/e-mission-phone/tree/master) -This is the phone component of the e-mission system. +__This is the phone component of the e-mission system.__ -:sparkles: This has now been upgraded to cordova android@9.0.0 and iOS@6.0.1 ([details](https://github.com/e-mission/e-mission-docs/issues/554)). It has also been upgraded to [android API 29](https://github.com/e-mission/e-mission-phone/pull/707/), [cordova-lib@10.0.0 and the most recent node and npm versions](https://github.com/e-mission/e-mission-phone/pull/708)It also now supports CI, so we should not have any build issues in the future. The limitations from the [previous upgrade](https://github.com/e-mission/e-mission-docs/issues/519) have all been resolved. This should be ready to build out of the box, after all the configuration files are changed. +:sparkles: This has now been upgraded to cordova android@12.0.0 and iOS@6.2.0. It has also been upgraded to [android API 33 and the latest iOS versions](https://github.com/e-mission/e-mission-docs/issues/934), [cordova-lib@10.0.0 and the most recent node and npm versions](). It also now supports CI, so we should not have any build issues in the future. __This should be ready to build out of the box.__ -Additional Documentation ---- +## Additional Documentation Additional documentation has been moved to its own repository [e-mission-docs](https://github.com/e-mission/e-mission-docs). Specific e-mission-phone wikis can be found here: https://github.com/e-mission/e-mission-docs/tree/master/docs/e-mission-phone **Issues:** Since this repository is part of a larger project, all issues are tracked [in the central docs repository](https://github.com/e-mission/e-mission-docs/issues). If you have a question, [as suggested by the open source guide](https://opensource.guide/how-to-contribute/#communicating-effectively), please file an issue instead of sending an email. Since issues are public, other contributors can try to answer the question and benefit from the answer. -Updating the UI only +:sparkles: Check [Contributing](#6-contributing) if you're interested in contributing for this project :sparkles: + +## Contents +#### 1. [Creating logos](#1-creating-logos) +#### 2. [Updating the UI only](#2-updating-the-ui-only) +#### 3. [Updating the e-mission-* plugins or adding new plugins](#3-updating-the-e-mission--plugins-or-adding-new-plugins) +#### 4. [End to End Testing](#4-end-to-end-testing) +#### 5. [Beta-testing debugging](#5-beta-testing-debugging) +#### 6. [Contributing](#6-contributing) + --- + +## 1. Creating logos + +If you are building your own version of the app, you must have your own logo to +avoid app store conficts. Updating the logo is very simple using the [`ionic +cordova resources`](https://ionicframework.com/docs/v3/cli/cordova/resources/) +command. + +**Note**: You may have to install the [`cordova-res` package](https://github.com/ionic-team/cordova-res) for the command to work + +## 2. Updating the UI only [![osx-serve-install](https://github.com/e-mission/e-mission-phone/workflows/osx-serve-install/badge.svg)](https://github.com/e-mission/e-mission-phone/actions?query=workflow%3Aosx-serve-install) If you want to make only UI changes, (as opposed to modifying the existing plugins, adding new plugins, etc), you can use the **new and improved** (as of June 2018) [e-mission dev app](https://github.com/e-mission/e-mission-devapp/) and install the most recent version from [releases](https://github.com/e-mission/e-mission-devapp/releases). ### Installing (one-time) -Run the setup script +1. Run the setup script ``` -$ bash setup/setup_serve.sh +bash setup/setup_serve.sh ``` - **(optional)** Configure by changing the files in `www/json`. Defaults are in `www/json/*.sample` ``` -$ ls www/json/*.sample -$ cp www/json/startupConfig.json.sample www/json/startupConfig.json -$ cp ..... www/json/connectionConfig.json +ls www/json/*.sample +cp www/json/startupConfig.json.sample www/json/startupConfig.json +cp ..... www/json/connectionConfig.json ``` ### Activation (after install, and in every new shell) - +2. Run this to activate ``` -$ source setup/activate_serve.sh +source setup/activate_serve.sh ``` ### Running @@ -46,7 +63,7 @@ $ source setup/activate_serve.sh 1. Start the phonegap deployment server and note the URL(s) that the server is listening to. ``` - $ npm run serve + npm run serve .... [phonegap] listening on 10.0.0.14:3000 [phonegap] listening on 192.168.162.1:3000 @@ -56,10 +73,10 @@ $ source setup/activate_serve.sh .... ``` -1. Change the devapp connection URL to one of these (e.g. 192.168.162.1:3000) and press "Connect" -1. The app will now display the version of e-mission app that is in your local directory - 1. The console logs will be displayed back in the server window (prefaced by `[console]`) - 1. Breakpoints can be added by connecting through the browser +2. Change the devapp connection URL to one of these (e.g. 192.168.162.1:3000) and press "Connect" +3. The app will now display the version of e-mission app that is in your local directory + 4. The console logs will be displayed back in the server window (prefaced by `[console]`) + 5. Breakpoints can be added by connecting through the browser - Safari ([enable develop menu](https://support.apple.com/guide/safari/use-the-safari-develop-menu-sfri20948/mac)): Develop -> Simulator -> index.html - Chrome: chrome://inspect -> Remote target (emulator) @@ -67,37 +84,68 @@ $ source setup/activate_serve.sh **Note1**: You may need to scroll up, past all the warnings about `Content Security Policy has been added` to find the port that the server is listening to. -End to end testing ---- -A lot of the visualizations that we display in the phone client come from the server. In order to do end to end testing, we need to run a local server and connect to it. Instructions for: +## 3. Updating the e-mission-\* plugins or adding new plugins -1. installing a local server, -2. running it, -3. loading it with test data, and -4. running analysis on it +[![osx-build-ios](https://github.com/e-mission/e-mission-phone/actions/workflows/ios-build.yml/badge.svg)](https://github.com/e-mission/e-mission-phone/actions/workflows/ios-build.yml) +[![osx-build-android](https://github.com/e-mission/e-mission-phone/actions/workflows/android-build.yml/badge.svg)](https://github.com/e-mission/e-mission-phone/actions/workflows/android-build.yml) -are available in the [e-mission-server README](https://github.com/e-mission/e-mission-server/blob/master/README.md). +__Important__ -In order to make end to end testing easy, if the local server is started on a HTTP (versus HTTPS port), it is in development mode. By default, the phone app connects to the local server (localhost on iOS, [10.0.2.2 on android](https://stackoverflow.com/questions/5806220/how-to-connect-to-my-http-localhost-web-server-from-android-emulator-in-eclips)) with the `prompted-auth` authentication method. To connect to a different server, or to use a different authentication method, you need to create a `www/json/connectionConfig.json` file. More details on configuring authentication [can be found in the docs](https://github.com/e-mission/e-mission-docs/blob/master/docs/install/configuring_authentication.md). +Most of the recent issues encountered have been due to incompatible setup. We +have now: +- locked down the dependencies, +- created setup and teardown scripts to setup self-contained environments with + those dependencies, and +- CI enabled to validate that they continue work. -One advantage of using `skip` authentication in development mode is that any user email can be entered without a password. Developers can use one of the emails that they loaded test data for in step (3) above. So if the test data loaded was with `-u shankari@eecs.berkeley.edu`, then the login email for the phone app would also be `shankari@eecs.berkeley.edu`. +If you have setup failures, please compare the configuration in the **passing CI +builds** with your configuration. That is almost certainly the source of the error. -Updating the e-mission-\* plugins or adding new plugins ---- -[![osx-build-ios](https://github.com/e-mission/e-mission-phone/actions/workflows/ios-build.yml/badge.svg)](https://github.com/e-mission/e-mission-phone/actions/workflows/ios-build.yml) -[![osx-build-android](https://github.com/e-mission/e-mission-phone/actions/workflows/android-build.yml/badge.svg)](https://github.com/e-mission/e-mission-phone/actions/workflows/android-build.yml) +### Tested on +__MacOS__ +- Intel chip, MacOS Ventura 13.6 +- Intel chip, MacOS Ventura 13.5.2 +- Intel chip, MacOS Ventura 13.0 +- Intel chip, MacOS Monterey 12.6.7 Pre-requisites --- -- the version of xcode used by the CI +- The version of xcode used by the CI. - to install a particular version, use [xcode-select](https://www.unix.com/man-page/OSX/1/xcode-select/) - or this [supposedly easier to use repo](https://github.com/xcpretty/xcode-install) - **NOTE**: the basic xcode install on Catalina was messed up for me due to a prior installation of command line tools. [These workarounds helped](https://github.com/nodejs/node-gyp/blob/master/macOS_Catalina.md). - git -- Java 11. Tested with [OpenJDK 11 (Temurin) using AdoptOpenJDK](https://adoptopenjdk.net/releases.html). -- android SDK; install manually or use setup script below. Note that you only need to run this once **per computer**. +- Java 17. Tested with [OpenJDK 17 (Temurin) using AdoptOpenJDK](https://adoptium.net). +- if you are not on the most recent version of OSX: `homebrew` + - this allows us to install the current version of cocoapods without + running into ruby incompatibilities - e.g. + https://github.com/CocoaPods/CocoaPods/issues/11763 + +__1. Export statements__ +``` +export ANDROID_SDK_ROOT="/Users//Library/Android/sdk" +``` +``` +export ANDROID_HOME="/Users//Library/Android/sdk" +``` +aka the path where you want the SDK to be installed. + +To setup JAVA_HOME (after installing the latest JDK ), run this command: +``` +/usr/libexec/java_home +``` +Find the location of the Java installation (Default will look something like this:) +``` +/Library/Java/JavaVirtualMachines/... +``` +and then export the package as: +``` +export JAVA_HOME="" +``` + +- android SDK; install manually or use setup script below (**recommended**). Note that you only need to run this once **per computer**. ``` - $ bash setup/prereq_android_sdk_install.sh + bash setup/prereq_android_sdk_install.sh ```
Expected output @@ -120,50 +168,27 @@ Pre-requisites ```
-- if you are not on the most recent version of OSX, `homebrew` - - this allows us to install the current version of cocoapods without - running into ruby incompatibilities - e.g. - https://github.com/CocoaPods/CocoaPods/issues/11763 -Important ---- -Most of the recent issues encountered have been due to incompatible setup. We -have now: -- locked down the dependencies, -- created setup and teardown scripts to setup self-contained environments with - those dependencies, and -- CI enabled to validate that they continue work. -If you have setup failures, please compare the configuration in the passing CI -builds with your configuration. That is almost certainly the source of the error. +__2. Installing (one time only)__ -Installing (one time only) ---- -Run the setup script for the platform you want to build +- Run the setup script for the platform you want to build ``` -$ bash setup/setup_android_native.sh +bash setup/setup_android_native.sh AND/OR -$ bash setup/setup_ios_native.sh +bash setup/setup_ios_native.sh ``` **(optional)** Configure by changing the files in `www/json`. Defaults are in `www/json/*.sample` ``` -$ ls www/json/*.sample -$ cp www/json/startupConfig.json.sample www/json/startupConfig.json -$ cp ..... www/json/connectionConfig.json +ls www/json/*.sample +cp www/json/startupConfig.json.sample www/json/startupConfig.json +cp ..... www/json/connectionConfig.json ``` -### Activation (after install, and in every new shell) - -``` -$ source setup/activate_native.sh -``` - -### Activation (after install, and in every new shell) - If connecting to a development server over http, make sure to turn on http support on android ``` @@ -171,39 +196,59 @@ If connecting to a development server over http, make sure to turn on http suppo ``` +__3. Run this in every new shell__ + +- __Activation__ +``` +source setup/activate_native.sh +``` +
Expected Output + +``` +Activating nvm +Using version 19.5.0 +Now using node v19.5.0 (npm v9.3.1) +npm version = 9.3.1 +Adding cocoapods to the path +Verifying /Users//Library/Android/sk or /Users//Library/Android/sdk is set +Activating sdkman, and by default, gradle +Ensuring that we use the most recent version of the command line tools +Configuring the repo for building native code +Copied config.cordovabuild.xml -> config.xml and package.cordovabuild.json -> package.json +``` + +
-### Run in the emulator +- __Pick a type of build and execute the following:__ +More "versions" are available in [`package.cordovabuild.json`](https://github.com/e-mission/e-mission-phone/blob/fce117ff859abd995613bd405dbc7d27c703b09b/package.cordovabuild.json) ``` -$ npx cordova emulate ios -AND/OR -$ npx cordova emulate android +npm run ``` -Creating logos ---- -If you are building your own version of the app, you must have your own logo to -avoid app store conficts. Updating the logo is very simple using the [`ionic -cordova resources`](https://ionicframework.com/docs/v3/cli/cordova/resources/) -command. +For instance: (build-dev-android) +``` +npm run build-dev-android +``` +Your output should look something like this: +![Build Successful Message screenshot](Build_ss.png) -**Note**: You may have to install the [`cordova-res` package](https://github.com/ionic-team/cordova-res) for the command to work +## 4. End to End Testing +A lot of the visualizations that we display in the phone client come from the server. In order to do end to end testing, we need to run a local server and connect to it. Instructions for: -Troubleshooting ---- -- Make sure to use `npx ionic` and `npx cordova`. This is - because the setup script installs all the modules locally in a self-contained - environment using `npm install` and not `npm install -g` -- Check the CI to see whether there is a known issue -- Run the commands from the script one by one and see which fails - - compare the failed command with the CI logs -- Another workaround is to delete the local environment and recreate it - - javascript errors: `rm -rf node_modules && npm install` - - native code compile errors: `rm -rf plugins && rm -rf platforms && npx cordova prepare` +1. installing a local server, +2. running it, +3. loading it with test data, and +4. running analysis on it -Beta-testing debugging ---- +are available in the [e-mission-server README](https://github.com/e-mission/e-mission-server/blob/master/README.md). + +In order to make end to end testing easy, if the local server is started on a HTTP (versus HTTPS port), it is in development mode. By default, the phone app connects to the local server (localhost on iOS, [10.0.2.2 on android](https://stackoverflow.com/questions/5806220/how-to-connect-to-my-http-localhost-web-server-from-android-emulator-in-eclips)) with the `prompted-auth` authentication method. To connect to a different server, or to use a different authentication method, you need to create a `www/json/connectionConfig.json` file. More details on configuring authentication [can be found in the docs](https://github.com/e-mission/e-mission-docs/blob/master/docs/install/configuring_authentication.md). + +One advantage of using `skip` authentication in development mode is that any user email can be entered without a password. Developers can use one of the emails that they loaded test data for in step (3) above. So if the test data loaded was with `-u shankari@eecs.berkeley.edu`, then the login email for the phone app would also be `shankari@eecs.berkeley.edu`. + +## 5. Beta-testing debugging If users run into problems, they have the ability to email logs to the maintainer. These logs are in the form of an sqlite3 database, so they have to be opened using `sqlite3`. Alternatively, you can export it to a csv with @@ -211,40 +256,68 @@ dates using the `bin/csv_export_add_date.py` script. ``` -$ mv ~/Downloads/loggerDB /tmp/logger. -$ pwd +mv ~/Downloads/loggerDB /tmp/logger. +pwd .../e-mission-phone -$ python bin/csv_export_add_date.py /tmp/loggerDB. -$ less /tmp/loggerDB..withdate.log +python bin/csv_export_add_date.py /tmp/loggerDB. +less /tmp/loggerDB..withdate.log ``` -Contributing ---- - -Add the main repo as upstream - - $ git remote add upstream https://github.com/covid19database/phone-app.git +## 6. Contributing -Create a new branch (IMPORTANT). Please do not submit pull requests from master - $ git checkout -b mybranch - -Make changes to the branch and commit them - - $ git commit - -Push the changes to your local fork - - $ git push origin mybranch - -Generate a pull request from the UI +1. Add the main repo as upstream +``` +2. git remote add upstream +``` +3. Create a new branch (IMPORTANT). Please do not submit pull requests from master +``` +4. git checkout -b +``` +5. Make changes to the branch and commit them +``` +6. git commit +``` + 7. Push the changes to your local fork +``` +8. git push origin +``` +9. Generate a pull request from the UI -Address my review comments +__\*__Address my review comments__\*__ Once I merge the pull request, pull the changes to your fork and delete the branch ``` -$ git checkout master -$ git pull upstream master -$ git push origin master -$ git branch -d mybranch +git checkout master +``` +``` +git pull upstream master +``` +``` +git push origin master +``` ``` +git branch -d +``` + +--- +### Troubleshooting +1. Xcode command line tools +``` +Warning: No developer tools installed. +You should install the Command Line Tools. +``` +``` +xcode-select --install +``` + +2. Creating Logos +- Make sure to use `npx ionic` and `npx cordova`. This is + because the setup script installs all the modules locally in a self-contained + environment using `npm install` and not `npm install -g` +- Check the CI to see whether there is a known issue +- Run the commands from the script one by one and see which fails + - compare the failed command with the CI logs +- Another workaround is to delete the local environment and recreate it + - javascript errors: `rm -rf node_modules && npm install` + - native code compile errors: `rm -rf plugins && rm -rf platforms && npx cordova prepare`