From 4c536ce439e67d5ee7e53f149fa5545c28687682 Mon Sep 17 00:00:00 2001 From: Erik Marks <25517051+rekmarks@users.noreply.github.com> Date: Wed, 26 Feb 2020 10:46:12 -0800 Subject: [PATCH] Update docs, scripts (#1338) * update docs, scripts * rename scripts: start -> watch, restart-packager-clean -> watch:clean --- README.md | 143 +++++++++++++++++++++++++++++++++++++++++++-------- package.json | 8 ++- 2 files changed, 128 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 6a665c1956e..8a2cbe3d7f5 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ ![MetaMask logo](logo.png?raw=true) + # MetaMask + [![CircleCI](https://circleci.com/gh/MetaMask/metamask-mobile/tree/develop.svg?style=shield)](https://circleci.com/gh/MetaMask/metamask-mobile/tree/develop) MetaMask is a mobile web browser that provides easy access to websites that use the [Ethereum](https://ethereum.org/) blockchain. @@ -10,57 +12,156 @@ To learn how to develop MetaMask-compatible applications, visit our [Developer D ## MetaMask Mobile -### Building locally +### Building Locally + The code is built using React-Native and running code locally requires a Mac or Linux OS. - Install [Node.js](https://nodejs.org) **version 10 (latest stable) and yarn@1 (latest)** - - If you are using [nvm](https://github.com/creationix/nvm#installation) (recommended) running `nvm use` will automatically choose the right node version for you. + - If you are using [nvm](https://github.com/creationix/nvm#installation) (recommended) running `nvm use` will automatically choose the right node version for you. -- Before starting, you need to install React Native dependencies: - - [MacOs](https://facebook.github.io/react-native/docs/getting-started.html#installing-dependencies-1) - - [Linux](https://facebook.github.io/react-native/docs/getting-started.html#installing-dependencies-2) -- Now clone this repo and then install all our dependencies. +- Install the shared React Native dependencies (`React Native CLI`, _not_ `Expo CLI`) + - [macOS](https://facebook.github.io/react-native/docs/getting-started.html#installing-dependencies-1) + - [Linux](https://facebook.github.io/react-native/docs/getting-started.html#installing-dependencies-2) + +- _MetaMask Only:_ Rename the `.*.env.example` files (remove the `.example`) in the root of the project and fill in the appropriate values for each key. Get the values from another MetaMask Mobile developer. + +- Clone this repo and install our dependencies: ```bash +git clone ... cd metamask-mobile -yarn install +yarn install # this will run a lengthy postinstall flow ``` -- Rename the `.*.env.example` files (remove the `.example`) in the root of the project and fill in the appropriate values for each key. -- Running the app on Android: +- Then, in one terminal, run: + +```bash +yarn watch +``` -You will need the `secret-tool` (a part of [libsecret-tools](https://launchpad.net/ubuntu/bionic/+package/libsecret-tools) package on Debian/Ubuntu based distributions) binary on your machine. You'll also want to have the android SDK; the easiest way to do that is by installing [Android Studio](https://developer.android.com/studio). Additionally, you'll need to install the Google Play Licencing Library via the SDK Manager in Android Studio. +#### Android + +- Install the Android SDK, via [Android Studio](https://developer.android.com/studio). + - _MetaMask Only:_ To create production builds, you need to install Google Play Licensing Library via the SDK Manager in Android Studio. +- Linux only: + - Ensure that you have the `secret-tool` binary on your machine. + - Part of the [libsecret-tools](https://launchpad.net/ubuntu/bionic/+package/libsecret-tools) package on Debian/Ubuntu based distributions. +- Install the correct emulator + - Follow the instructions at: + - [React Native Getting Started - Android](https://facebook.github.io/react-native/docs/getting-started.html#installing-dependencies-1) _(React Native CLI Quickstart -> [your OS] -> Android)_ + - More details can be found [on the Android Developer site](https://developer.android.com/studio/run/emulator) + - You should use the following: + - **Android OS Version:** Latest, unless told otherwise + - **Device:** Google Pixel 3 +- Finally, start the emulator from Android Studio, and run: ```bash yarn start:android ``` -- Running the app on iOS: +#### iOS + +- Install the iOS dependencies + - [React Native Getting Started - iOS](https://facebook.github.io/react-native/docs/getting-started.html#installing-dependencies-1) _(React Native CLI Quickstart -> [your OS] -> iOS)_ + - You do **not** need CocoaPods +- Install the correct simulator + - **iOS OS Version:** Latest, unless told otherwise + - **Device:** iPhone 11 Pro ```bash yarn start:ios ``` -### Running tests: - - Unit test: +#### Build Troubleshooting + +Unfortunately, the build system may fail to pick up local changes, such as installing new NPM packages or `yarn link`ing a dependency. +If the app is behaving strangely or not picking up your local changes, it may be due to build issues. +To ensure that you're starting with a clean slate, close all emulators/simulators, stop the `yarn watch` process, and run: + +```bash +yarn clean + +# if you're going to `yarn link` any packages, +# do that here, before the next command + +yarn watch:clean + +# ...and then, in another terminal + +yarn start:ios + +# or + +yarn start:android ``` + +If `yarn link` fails after going through these steps, try directly `yarn add`ing the local files instead. + +### Debugging + +First, make sure you have the following running: + +- `yarn watch` +- Your Android emulator or iOS simulator +- `yarn start:android` or `yarn start:ios` + +Next, check that the React Native Debugger is working: + +- Open your emulator or simulator, and select `Debug JS Remotely` from its menu + - You can also try to navigate to this URL in Chrome: http://localhost:8081/debugger-ui/ +- If that doesn't take you to the React Native Debugger, something is wrong + +#### Debugging iOS (macOS Only) + +For more details, see [this page](https://medium.com/@mattcroak718/debugging-your-iphone-mobile-web-app-using-safari-development-tools-71240657c487). + +- You should be able to inspect the mobile app using the console in the React Native Debugger tab +- To debug a website (dapp) in the browser: + - Navigate to the website in the app's browser + - Open Safari + - Go to: _Preferences -> Advanced_ and select `Show Develop menu in menu bar` + - Select `Develop` in the menu bar + - Find your simulator in the second section from the top + - Select the relevant WebView from the list + - The simulator will highlight the WebView when you hover over it in Safari + +#### Debugging Android + +For more details, see [this page](https://developers.google.com/web/tools/chrome-devtools/remote-debugging/webviews). + +- You should be able to inspect the mobile app using the console in the React Native Debugger tab +- To debug a website (dapp) in the browser: + - Navigate to the website in the app's browser + - Go to chrome://inspect + - Select the relevant WebView under **Remote Target** + +#### Miscellaneous + +- [Troubleshooting for React Native](https://facebook.github.io/react-native/docs/troubleshooting#content) + +### Running Tests + +- Unit tests: + +```bash yarn test:unit ``` - - E2E Tests (iOS) -``` + +- E2E tests (iOS) + +```bash yarn test:e2e:ios ``` - - E2E Tests (Android) -``` + +- E2E tests (Android) + +```bash yarn test:e2e:android ``` ### Architecture -To get a better understanding of the internal architecture of this app take a look at [this diagram](https://github.com/MetaMask/metamask-mobile/blob/develop/architecture.svg) - -### Troubleshooting -Visit [Troubleshooting for React Native](https://facebook.github.io/react-native/docs/troubleshooting#content) +To get a better understanding of the internal architecture of this app take a look at [this diagram](https://github.com/MetaMask/metamask-mobile/blob/develop/architecture.svg). ## License diff --git a/package.json b/package.json index 6dda3209055..2f25810f308 100644 --- a/package.json +++ b/package.json @@ -3,8 +3,12 @@ "version": "0.2.13", "private": true, "scripts": { - "restart-packager-clean": "watchman watch-del-all && rm -rf $TMPDIR/react-* && yarn start -- --reset-cache", - "start": "node node_modules/react-native/local-cli/cli.js start", + "watch": "node node_modules/react-native/local-cli/cli.js start", + "watch:clean": "watchman watch-del-all && rm -rf $TMPDIR/react-* && yarn watch -- --reset-cache", + "clean:ios": "rm -rf ios/build", + "clean:android": "rm -rf android/build", + "clean:node": "rm -rf node_modules && yarn install", + "clean": "yarn clean:ios && yarn clean:android && yarn clean:node && yarn install", "lint": "eslint '**/*.js' --ignore-path=.prettierignore", "lint:fix": "eslint '**/*.js' --fix --ignore-path=.prettierignore", "format": "prettier '**/*.{js,json}' --write",