Waterfox for Android

The all-new Waterfox for Android browser is based on GeckoView and Mozilla Android Components.

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.

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.

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.

./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.

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.

./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.

./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.

cd ../
git clone [email protected]: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:

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:

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.

# 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:

./gradlew clean app:assembleDebug

To build a release version:

./gradlew clean app:assembleRelease

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