LeOSium-WF/README.md

# Waterfox for Android

The all-new Waterfox for Android browser is based on [GeckoView](https://mozilla.github.io/geckoview/) and [Mozilla Android Components](https://mozac.org/).

## License

    This Source Code Form is subject to the terms of the Mozilla Public
    License, v. 2.0. If a copy of the MPL was not distributed with this
    file, You can obtain one at http://mozilla.org/MPL/2.0/

## Building with Local Android Components

To build Waterfox for Android with local Android components - as opposed to via Android Studio and Mozilla's Maven respository - you'll first need to build GeckoView from source and then build Waterfox for Android itself, pointing it to your local GeckoView build.

These instructions are based on if you were to start from a clean Linux distribution installation.

### 1. Clone and Prepare GeckoView

First, clone the Firefox repository (which contains GeckoView). These instructions assume you will clone it into a directory named `firefox`. We do not care about the commit history, so we are shallow cloning.

```shell
git clone --depth 1 --branch release https://github.com/mozilla-firefox/firefox/
cd firefox
```

### 2. Install Python Dependencies

Ensure you have `python3-pip` installed, which is required by Mozilla's build scripts.

```shell
sudo apt-get install python3-pip
```

### 3. Bootstrap GeckoView

Run the `mach` bootstrap command to set up the build environment for GeckoView specifically for Android.

```shell
./mach --no-interactive bootstrap --application-choice="GeckoView/Firefox for Android"
```

### 4. Configure the GeckoView Build

Create a `.mozconfig` file in the `firefox` directory with the necessary build options. This configuration enables the Android mobile project, optimizes the build, disables debug symbols, and enables GeckoView Lite.

```shell
rm -f mozconfig
cat > .mozconfig << 'EOF'
ac_add_options --enable-project=mobile/android
ac_add_options --enable-optimize
ac_add_options --disable-debug
ac_add_options --enable-geckoview-lite
EOF
```

### 5. Build GeckoView

Compile GeckoView and its binaries. This can take a significant amount of time.

```shell
./mach build && ./mach build binaries
```

### 6. Publish GeckoView to Maven Local

Publish the GeckoView and Exoplayer2 artifacts to your local Maven repository. This makes them accessible to the Waterfox for Android build system.

```shell
./mach gradle geckoview:publishDebugPublicationToMavenLocal
./mach gradle exoplayer2:publishDebugPublicationToMavenLocal
```

### 7. Clone Waterfox-Android

Navigate out of the `firefox` directory (or whatever you named your GeckoView clone) and clone the Waterfox-Android repository.

```shell
cd ../
git clone git@github.com:BrowserWorks/Waterfox-Android.git
cd Waterfox-Android
```

### 8. Configure Local Properties for Waterfox-Android

Create a `local.properties` file in the root of the `Waterfox-Android` project. This file tells the Waterfox build system where to find your locally built GeckoView.

Execute the following command in the `Waterfox-Android` directory:

```shell
cat > local.properties << 'EOF'
dependencySubstitutions.geckoviewTopsrcdir=/home/$USER/firefox
dependencySubstitutions.geckoviewTopobjdir=/home/$USER/firefox/obj-$TRIPLET
EOF
```

The `dependencySubstitutions.geckoviewTopsrcdir` path should point to the root of your GeckoView source code (e.g., the `firefox` directory you cloned in Step 1). The `dependencySubstitutions.geckoviewTopobjdir` path should point to the object directory within your GeckoView build, which is typically `obj-` followed by your architecture triplet (e.g., `obj-x86_64-unknown-linux-android`).

For example, if you cloned GeckoView to `/workspace/firefox` and your object directory is `/workspace/firefox/obj-x86_64-unknown-linux-android`, your `local.properties` would look like:

```Waterfox-Android/local.properties#L1-2
dependencySubstitutions.geckoviewTopsrcdir=/workspace/firefox
dependencySubstitutions.geckoviewTopobjdir=/workspace/firefox/obj-x86_64-unknown-linux-android
```

### 9. Set Environment Variables

Set the `JAVA_HOME` and `ANDROID_HOME` environment variables. The paths shown below are typical for a `.mozbuild` setup (created during GeckoView bootstrap) but might differ on your system. Ensure these point to a JDK 17 and a valid Android SDK.

```shell
# These paths might differ based on your .mozbuild setup
export JAVA_HOME=$HOME/.mozbuild/jdk/jdk-17.0.13+11/ # Or your JDK 17 path
export ANDROID_HOME=$HOME/.mozbuild/android-sdk-linux/ # Or your Android SDK path
```

### 10. Build Waterfox-Android

Finally, clean and build the Waterfox for Android application.

To build a **debug** version:

```shell
./gradlew clean app:assembleDebug
```

To build a **release** version:

```shell
./gradlew clean app:assembleRelease
```

Note: For release builds, you will need to have set up signing configurations as per standard Android development practices.