-[Install and start the app (iOS)](#install-and-start-the-app-ios)
-[React native](#react-native)
-[Contributing](#contributing)
-[Troubleshooting](#troubleshooting)
Some of the information is duplicated from the [React native developer docs.](https://reactnative.dev/docs/getting-started)
## Get logins
In order to test, make an account on a Mahara instance. In order to generate an authentication token please see [this documentation](https://manual.mahara.org/en/19.10/account/apps.html?highlight=authentication%20token).
## Installing dependencies
Install *Node*, the *React Native command line interface*, a *JKD*, and *Android Studio*.
### Install Node 15 or newer
Follow the [installation instructions for your Linux distribution](https://nodejs.org/en/download/package-manager/) to install Node 15 or newer.
```bash
# Update package manager
sudo apt update
# Install nodejs and npm using apt package manager
sudo apt install nodejs npm
# Verify nodejs installation
nodejs -v
# Verify npm installation
npm -v
```
### Install React Native CLI
```bash
npm install-g react-native-cli
```
If you get an error like Cannot find module ‘npmlog’ you can install npm directly using this command. If the above command run successfully then no need to run this command
```bash
curl -0-L https://npmjs.org/install.sh | sudo sh
```
### Install Java Development Kit
React Native requires version 8 of the Java SE Development Kit (JDK) as 1.8 is more stable. Consequently, we will need to set Java 1.8 as default, for do that run the below command.
Alternatively, you may download and install [OpenJDK](https://openjdk.java.net/) from [AdoptOpenJDK](https://adoptopenjdk.net/) or your [system packager](https://tecadmin.net/install-oracle-java-8-ubuntu-via-ppa/). You may also download and install Oracle JDK 8 if desired.
# OpenJDK 64-Bit Server VM (build 25.242-b08, mixed mode)
```
### Android development environment
>(for a virtual device) - [skip next](#clone-project-into-local-directory) if you are using a physical device
#### Set up through Jetbrains Toolbox (Option 1)
[Download the JetBrains Toolbox app](https://www.jetbrains.com/toolbox-app/) for easy installation and management of Android Studio.
Note: you may need to run `sudo apt-get install -y libfuse2`
1. Once JetBrains Toolbox is set up and open, and install Android Studio in the 'Available' list.
2. Open up Android Studio from the Toolbox after completion of download.
3.[Follow the steps on the React Native docs for correct set up of Android Studio.](https://reactnative.dev/docs/environment-setup)
#### Manual setup (Option 2)
Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to follow the next few steps carefully.
1.**Install Android Studio**
[Download and install Android Studio.](https://developer.android.com/studio/index.html) Choose a "Custom" setup when prompted to select an installation type. Make sure to check the boxes next to all of the following :
1. Android SDK
2. Android SDK Platform
3. Android Virtual Device
2.**Install the Android SDK**
Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 11 SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.
The SDK Manager can be accessed from the "Welcome to Android Studio" screen. Click on "Configure", then select "SDK Manager".
> The SDK Manager can also be found within the Android Studio "Preferences" dialog, under **Appearance & Behavior** → **System Settings** → **Android SDK**.
Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 11 entry, then make sure the following items are checked:
- `Android SDK Platform 30`
-`Intel x86 Atom_64 System Image` or `Google APIs Intel x86 Atom System Image`.
Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that latest 30.x.x is selected.
Finally, click "Apply" to download and install the Android SDK and related build tools.
3.**Configure the ANDROID_HOME environment variable**
The React Native tools require some environment variables to be set up to build apps with native code.
```bash
# Check which bash file you are using with
cat$HOME/.bash_profile
# If there is a file with this name open it up with
gedit $HOME/.bash_profile
# If it says No such file or directory, check another bash file
cat$HOME/.bashrc
# If there is a file with this name open it up with
gedit $HOME/.bashrc
```
Add the following lines to your `$HOME/.bash_profile` or `$HOME/.bashrc` config file:
```bash
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
```
> `.bash_profile` is specific to `bash`. If you're using another shell, edit the appropriate shell-specific config file.
Type `source $HOME/.bash_profile` to load the config into your current shell. Verify that `ANDROID_HOME` has been added to your path by running `echo $PATH`.
> Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under **Appearance & Behavior** → **System Settings → Android SDK.**
## Make a copy of the project
### Forking the GitHub repository (community contributors)
Make a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of <https://github.com/MaharaProject/mahara-mobile-react-native> to your own GitHub account.
> 🌐 If you are a translator, the following steps are optional if you'd like to install the app to see your changes.
### Clone project into your local directory (maintainers)
1. In your terminal navigate into the desired folder to place the project.
2. In the folder where you want to clone the project into, execute the command
-[Install and start the app (iOS)](#install-and-start-the-app-ios)
-[React native](#react-native)
-[Contributing](#contributing)
-[Troubleshooting](#troubleshooting)
Some of the information is duplicated from the [React native developer docs.](https://reactnative.dev/docs/getting-started)
## Get logins
In order to test, make an account on a Mahara instance. In order to generate an authentication token please see [this documentation](https://manual.mahara.org/en/19.10/account/apps.html?highlight=authentication%20token).
## Installing dependencies
Install _Node_, the _React Native command line interface_, a _JKD_, and _Android Studio_.
### Install Node 18 or newer
Follow the [installation instructions for your Linux distribution](https://nodejs.org/en/download/package-manager/) to install Node 18 or newer.
```bash
# Update package manager
sudo apt update
# Install nodejs and npm using apt package manager
sudo apt install nodejs npm
# Verify nodejs installation
nodejs -v
# Verify npm installation
npm -v
```
### Install React Native CLI
```bash
npm install-g react-native-cli
```
If you get an error like Cannot find module ‘npmlog’ you can install npm directly using this command. If the above command run successfully then no need to run this command
```bash
curl -0-L https://npmjs.org/install.sh | sudo sh
```
### Install Java Development Kit
React Native requires version 8 of the Java SE Development Kit (JDK) as 1.8 is more stable. Consequently, we will need to set Java 1.8 as default, for do that run the below command.
Alternatively, you may download and install [OpenJDK](https://openjdk.java.net/) from [AdoptOpenJDK](https://adoptopenjdk.net/) or your [system packager](https://tecadmin.net/install-oracle-java-8-ubuntu-via-ppa/). You may also download and install Oracle JDK 8 if desired.
# OpenJDK 64-Bit Server VM (build 25.242-b08, mixed mode)
```
### Android development environment
> (for a virtual device) - [skip next](#clone-project-into-local-directory) if you are using a physical device
#### Set up through Jetbrains Toolbox (Option 1)
[Download the JetBrains Toolbox app](https://www.jetbrains.com/toolbox-app/) for easy installation and management of Android Studio.
Note: you may need to run `sudo apt-get install -y libfuse2`
1. Once JetBrains Toolbox is set up and open, and install Android Studio in the 'Available' list.
2. Open up Android Studio from the Toolbox after completion of download.
3.[Follow the steps on the React Native docs for correct set up of Android Studio.](https://reactnative.dev/docs/environment-setup)
#### Manual setup (Option 2)
Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to follow the next few steps carefully.
1.**Install Android Studio**[Download and install Android Studio.](https://developer.android.com/studio/index.html) Choose a "Custom" setup when prompted to select an installation type. Make sure to check the boxes next to all of the following :
1. Android SDK
2. Android SDK Platform
3. Android Virtual Device
2.**Install the Android SDK**
Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 11 SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.
The SDK Manager can be accessed from the 'Welcome to Android Studio' screen. Click on 'Configure', then select 'SDK Manager'.
> The SDK Manager can also be found within the Android Studio "Preferences" dialog, under **Appearance & Behavior** → **System Settings** → **Android SDK**.
Select the 'SDK Platforms' tab from within the SDK Manager, then check the box next to 'Show Package Details' in the bottom right corner. Look for and expand the Android 11 entry, then make sure the following items are checked:
-`Android SDK Platform 30` -`Intel x86 Atom_64 System Image` or `Google APIs Intel x86 Atom System Image`.
Next, select the 'SDK Tools' tab and check the box next to 'Show Package Details' here as well. Look for and expand the 'Android SDK Build-Tools' entry, then make sure that the latest 30.x.x is selected.
Finally, click 'Apply' to download and install the Android SDK and related build tools.
3.**Configure the ANDROID_HOME environment variable** The React Native tools require some environment variables to be set up to build apps with native code.
```bash
# Check which bash file you are using with
cat$HOME/.bash_profile
# If there is a file with this name open it up with
gedit $HOME/.bash_profile
# If it says No such file or directory, check another bash file
cat$HOME/.bashrc
# If there is a file with this name open it up with
gedit $HOME/.bashrc
```
Add the following lines to your `$HOME/.bash_profile` or `$HOME/.bashrc` config file:
```bash
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
```
> `.bash_profile` is specific to `bash`. If you're using another shell, edit the appropriate shell-specific config file.
Type `source $HOME/.bash_profile` to load the config into your current shell. Verify that `ANDROID_HOME` has been added to your path by running `echo $PATH`.
> Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under **Appearance & Behavior** → **System Settings → Android SDK.**
## Make a copy of the project
### Forking the GitHub repository (community contributors)
Make a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of https://github.com/MaharaProject/mahara-mobile-react-native to your own GitHub account.
> :globe_with_meridians: If you are a translator, the following steps are optional if you'd like to install the app to see your changes.
### Clone project into your local directory (maintainers)
1. In your terminal navigate into the desired folder to place the project.
2. In the folder where you want to clone the project into, execute the command
4. Next, on a new terminal tab/window. `cd` into the same directory as before.
## Run the app on a device/emulator
### Virtual device testing - on Emulator with Android studio
1. Generate (make sure you have Android Studio and a virtual device running) and run on Android with
```bash
npm run android
```
### Physical device testing
Referenced from [React Native](https://reactnative.dev/docs/running-on-device)
1. Open developer mode on your Android device. [Check here for tips](https://www.digitaltrends.com/mobile/how-to-get-developer-options-on-android/)
1. Inside of the developer options: Allow USB debugging.
2. Connect your device to your pc via USB connection.
3. Your device will get a request for permissions:
1. Allow access to files/Transfer files.
2. Allow USB Debugging. OK
4. On your terminal, execute the command:
```bash
adb devices
```
This will list the devices connected to the pc.
```bash
List of devices attached
01234SDGESG567890 device
# If you have not allowed USB debugging it will show
# 01234SDGESG567890 unknown
```
5. Run the app on the connected device with command:
```bash
# Insert the appropriate number shown in your terminal.
npm run android -d 01234SDGESG567890
```
## Install and start the app (iOS)
In an macOS machine, open the .workspace file in XCode. Run npm install and pod install. Select a virtual machine and build.
## React native
Follow official docs: https://facebook.github.io/react-native/docs/getting-started.html.
This is because the installation process changes a lot, and we can't keep these docs up to date.
# Contributing
Now that we have gotten Mahara mobile installed and ready to run, let's start contributing! [Let's contribute!!! :bulb:](https://git.mahara.org/mahara-mobile/mahara-mobile-react-native/-/wikis/Contributing-to-Mahara-mobile)
# Troubleshooting
Changes made but not seeing anything different?: Try cleaning the cache in Gradle with `cd android && ./gradlew clean`
Virtual device open but app not running? You might need to install adb with:
`sudo install adb`
Something something permissions? You may need to CHOWN kvm or Gradle folders:
